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stay In Control Wherever You Go. 



There 


For more than a decade, Timbuktu Pro and netOctopus 
have been the leading remote control, file transfer and 
systems administration applications for the Mac OS. 


Now, both of these Indispensable tools 
are updated to take full advantage of the 
world's most advanced operating system. 


Windows XP Ready 


Timbuktu Pro 

Whether you're at home or at work, Timbuktu Pro allows you to operate distant 
computers as if you were sitting in front of them, transfer files or folders quickly 
and easily, and communicate by instant message, text chat, or voice intercom, 
http;//WWW.timbuktupro.com 


netOctopus 

Intuitive and powerful, netOctopus can manage a network of ten or 10,000 
computers. Inventory computers, software and devices on your network; distribute 
software: configure remote computers; and create custom reports on the fly. 
http://www.netoctopus.com 


Learn more, try it, or buy it online. Call us at l-800-485>S741. 
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YOUR DATABASE SERVER WITH THE 

C-TREE’SERVER SDK 



• Enhance our server with your own 
custom server-side functionaiity 

• Move functionality from the client-side lo 
the server-side to reduce network traffic 
and increase pcrfoimancc 

• Modify or replace entire server 
subsystems 

• Complete source for the server 
mainline, key server 
subsystems, and client-side 

• Flexible OEM licensing 


Today’s database demands are often too complex for traditional database servers. 
The functionality and precise level of control you need is simply not available. 
Perhaps you need alternate sort criLcria ibr your data or a special twist in the 
threading or communication logic. 

FairCom’s c-tree® Server SDK allows you to create a customized, 
industrial-strength server designed for your particular needs. Use 
FairCom’s kernel, with over 20 years of proven stability, or override 
functionality within specific subsystems to implement your own 
subtleties. Move your application’s data I/O functions to the 
server-side to decrease network traffic and increase 
performance! 

FairCom’s c-tree Server SDK is used by companies 
worldwide such as Software AG and Citibank®. It’s 
integrated seamlessly into c-tree Plus and includes 
complete source code to the server mainline and all the 
interface subsystems to the c-lree Server. And 
best of all, once you’ve created your unique, 
customized server, it is easy to install and 
administer: no DBA required! 


Visit www.faircom.cam/ep/mt/sdk today to take control of your server! 
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SYBASE INTEGRATION TECHNOLOGIES. EVERYTHING WORK 


Adaptive SeWer 
Enterprise 12.5 
MAC 05 X 


F|i EMAKER ?*?0 CUSTOM 

SCALE TO NEW HEIGHTS 


Sybase is helping 
leading companies achieve 
Information Liquidity: a highly 
profitable state where aif of 
your information is translbrmed 
into real economic value. 


Want to enhance the performance 
of FileMaker Pro on MAC OS X? 
The same database engine that 
runs Wall Street can help you do 
just that 


ASE 12.5 increases the reliability, 
availability and scalability of 
your FileMaker Pro application. 
It provides better data integrity, 
world-class security and the 
ability to handle thousands of 
transactions per minute, it'll 
also give your users the power 
of SQL queries. 


A FREE Developer's Edition 
download is available online 
at svbase.com/filemakef. 


ASE 12.5 for MAC OS X is yet 
one more example of how 
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GETTING 

STARTED 


Copyright 2003 by Dave Mark 


Getting Started: 
Xcode Rising 


Bcuuiiful weather. A gorgeous new venue called Moscone 
West. And a keynote l>y Steve Jobs. Ah, the annual pilgrimage to 
Applets World Wide Developers Conference. 1 had a great time 
and met a lot of you at the conference. Moscone West is acrtiss 
4^ street from Moscone Center, the traditional site of MacWorld 
Expo, A state of the art facility, WWDC marked its maiden 
voyage. Yes, we were the first conference ever lield here. Cooil 
As usual, Steve Jobs did an excellent job with the keynote 
(check out Scott Knaster's July column for a blow-by-blow 
account). My favorite part was when Steve rolled out Xcode, 
Apple's replacement for Frojea Builder. Everyone who attended 
the conference got a set of Xcode disks, one install for Panther 
and another for jagttar. Since Panther is .still not released, I 
thought I'd fcxiis on the jaguar version of Xccxle. 

XcoDt In, PROjEtn' Bonj^FR Oirr 

To start off' our guided tour of Xcode, let's take a classic 
Project Builder project and open it in Xcode, First, launch the 
Xcode app. You'll find it in /Dmmhiier/Applicuiiom. Once 
Xccxle launches, selea Open from the File menu. Navigate into 
tltc Sample Ctxle directory in /l}eveloper/Examples/AppKii/, We’ll 
he playing witli tlte Sketch project. In Xcode’s open dialog, you 
could click on the Sketch directory, then scroll through all the 
files looking for the project file. But do tills instead: Click on the 
Sketch direaory, then click the Ofjen button without selecting a 
file to open. Xcode will find and open the first project file it 
encounters in that directory. Cool! 

Yeah, 1 know, why not just find the project file in the 
Finder and double-click it? 'I'wo reasons. First, I wanted to 
show off Xccxle's ability to auto-open the projea file. And 
.second, I still have Project Builder installed on my 
machine. Since Sketch's project is a Project Builder file, 
when 1 doubleclick on the project, the Finder launches 
Projea Builder. 


Another solution: In the Finder, cEck on the project file, 
tlien do a Command-i to bring up the Get Info window 
(see Figure 11 Click on the Open with: disclosure triangle 
and select Xcode from the popup menu. If you Imve not 
yet run Xcode, selea Other,., from the popup and go find 
the Xcode app. You can click on the OmngeAU.., button 
to make this change for all your Project Builder projects. 

ee Sketch, pbxproj Info 

▼ General: 

H Sketch.pbxproj 

Kind: Project Sullder Project File 
Size: 16 KB an disk (12,636 bytest 
Where: Desk top: Sketch: 

Created: Toe, Hov 5. 2002, 1:20 PM 

Modified: Tue, Jul IS, 2001. 4:IB PM 

Q Stationery Pad 
Locked 

► Name A Extension: 

▼ Open with : 


► Preview: 

► Ownership & Permissions: 

► Comments: 


Fifiure L Use the Finder's Get Info umdow to force your Pnjject 
Builder projects to open with Xcode. 


j ✓ yj: Project Builder (defaults 


i'Ji Xcode 



Dave Mark i.s a long-time Mac developer and MacTech contributor. Author of more than a dozen books on various Mac-development topics, he’s also 
a founding partner of the nationally syndicated Oniine Tonight and Net Music Counidoum radio programs. All this and now he’s got some fish! 
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When you click the Open button, Xcode will warn you that 
you are opening an old project file and that it will be upgraded 
if you continue (See Figure 2). Not a prob. Click the 
button and let*s charge forward* 



Warning 

The project ^etch.pbxf^oj* was saved with an older 
version of Xcode. Opening tt in this version will cause 
it to be upgraded, which may prevent older versions 
of Xcode from reading it* Are you sure you want to 
open it? 


Don’t Open ^ Qp<n 


Figure 2* Warning! are opening an old project Jile. 



It mil be assimilated. 


Figure 3 .shows the Sketch project window that appears 
once Xcode upgrades the old Project Builder project file. If your 
project window looks radically different, fjerliaps youVe 
mucked with the preferences or customized the toolbar (the 
strip of icons at the top of the window)* lb get back the original 
toolbar, select Customize Ibolbar.. from the View menu, drag 
die default toolbar from the lK>ttom of die window that appears 
to the UK>ll>ar at the top of the window, then click Done. 
Definitely worth spending a minute or two with this, just to get 
a sense of the kinds of changes you can make to your toolbar* 


Fetch 


«ee 


, SkMOi 


'S. 'k. • B -A O 


t V ft 

• Cnwm « fm 

B 

Eiri&ra widWantrmi 
hdplcimfllMlcin fVc 
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■ DrjmWtKkM.nilj 

S tridPU«t.AUl 
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Figure JL The Sketch project window. 


Off the leash. 


A Whole New Build System 

When Xcode upgrades an existing project file, it converts 
the project file format, but does not convert the targets 
themselves* To understand wlial this means, you have to know 
a litde bit about build systems. Project Builder originally used 
Make as its build system. Make is a traditional Unix utility that 
parses dependencies listed in a texi-based makefile. 



Fetchsoflworks.com 


Version 4.0.3 now available. 
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If Make Is new to you, take a minute, fire up Terminal 
and type in the command man make. This will list the 
man pages for the make command and will give you the 
basics on build systems. 

(Tver time, Projea Builder moved to an open Mmrc'e build 
system named Jam. Here‘s a link that’ll give you the basics on Jam: 

http://www.perforce-com/jaTri/jam,html 

Jam offers a more compact and sophisticated build 
language than Make, but is still a text-based build system. 

Xcode uses its own, native build system, a build system that 
is more tigliUy integrated with the IDE, has a better 
understanding of the project dependencies and, therefore, 
prcxiuces belter build performance. Since the command line and 
graphical versioas c}f the build system were themselves built 
from the same frameworks, there is no noticeable performance 
change when you move between tiie two. 

You can still use the legacy build mechanisms that work with 
Projea Builder, Howev^er, you'll need to move u> “native 
builds" if you want to Uike adv^tage of Xcode features Ike 
Zero Link, Fix and Continue, and Distributed Builds. 


Upgrading the Sketch Target 

Our next step is to upgrade the Sketch target so it use.s 
Xcode’s native build system. In the project window's CmufiK & 
files pane, click on llte Targets disclosure triangle to reveal the 
list of targets in this project. At iliis point, there is a single target, 
named Sketch. Click on Sketch, tlien select Upgrade Taipei to 
Native froin the Project menu. 

A panel will appear in tlic project tvindow that tells you 
what is al^oiil to happen and gives you a chance to name your 
new target (Figure 4). I^ave the name as Sketch (Upgraded) and 
click the Upgrade button. 


Up^rad# Tirgtt 

Your Ufo«i ^ll bt to 9 r»t>vv target uiing tbc (oitlowkif grocedure 

- A itew copv of your Urgti wiN be creaied. 

« 1 copy will be a naihw target conbgured lo prdduce the appropnaic product tygv. 

• An inrq.fdiii file the iwgert ptoduci Ketttn^ will bt added lo the pnoieci 

• on oibci i^rpeti wUi bo preicrved in th* otw copy, 

« PepePdontics of other targefi will ntrt bo OKtendod to include the now copy. 

- iawa and AppleScript ar« not preitrinty tuppon«d by nafiMt largotj. $o you should not upgrade 
lotgeti wbKh fomatn eiiher pf iho*t bnguages. 


Name tot Upwaded Target: SliMcb |t%>fntMlf 


f Cancel ) f tlpyirio j 

A 

Figure 4. Namingyournew, natitetarget. 


Now, when you look at the list of targets in die project 
window, you’ll see your new Sketch (Upgraded) target. Select 
Sketch (Upgraded) from the popup in the upper-left corner of 
the projea window to make this target the active target 


(Figure 5)^ Note that the active target has a small green 
checkmark in iLs icon. 

Aaive targets are imponand Wlien you do a run, build, 
or debug, the active target is the one that is run, built, or 
debugged. You might have one target with full debug 
info aimed on, and a second target that is optimized widi 
no debug info. You might have one target that uses a 
legacy build system and another that uses Xcode's native 
build system, Make sure you have the right active target 
selected before you do your build. 


eee 
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Figure 5* Mak^ the netv, Sketch (Upgraded) 
target the actii^* target. 

Xcode uses tiie inspcaor window to modify target settings. 
As an example, select tiie Sketch (Uprade) entry under Targets, 
then bring up the inspeaor window (eitiier click do the fin^- 
circle on the tcK>lbar, or type command-i). In the inspeaor 
window, click on the Build tali. Each entry in this list is a setting 
followed by a value. Some values are set via popup mcnu.s, 
some by typing in text, others with checkmarks. Depends on the 
setting type. 

Take a careful look at Figure 6. There's a lot going on here. 
First, I clicked on the Build ral>, then clicked on the little 
"drawer'" icon in the lower left corner of tfie inspector window. 
This opened the drawer to the side, which allows me to select 
from difierent set.s of settings. 

I then clicked on the Prehinding setting to selea it, then 
clicked on tlie split bar at the lx>itom of the window and 
dragged it up, revealing an explanation of this setting. 

Note also dmt iliere i.s a search field at the bottom of this 
window. Suppose there were hundreds of settings and I 
wanted to find anything to do with optimization. If I type 
“optim” in tile search held, the settings are whittled down to 
two, one of which is called Optimization level and the other 
of which ha.s the word optimization in its explanation text. 
Very powerfol stuff. 
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figure 6. The inspector window, sbomng the buiid options 
for the Sketch (Upgraded) target. 


ITie Groups & Files Pane 

On tl)e left side of the projea window and just under the 
active tai|;et popup, you 11 find the Groups & Fiks Pane. First in 
this list is the Files Groups which lists all tlie fdes that make up 
y<mr project. If you click on Ms group, you1l see an alphabetical 
listing of all the project’s files, including your Classes, Other 
Sources (such as mam*m and any precompiled headers). 
Resources (CrediLs.rtf, Info.plist, InfoPlist.strings, and your nib 
files), Frameworks, and the Products produced by your project. 

Figure 7 shows a default project, based on a Cocoa 
Dcx-umenl-Based Application template. The five sub-groups that 
make up the test Files Group are what you get when you create 
your project. As you might expect, you can create new 
.subgroups (conirohclick on a group name and selea New Group 
from tlte contextual menu and edit the name of any group 
(option-click on the name). You can also click and drag any 
group to move it up and down in the list or place it within 
another group in the hierarchy. Very intuitive. Very nice. 
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Figure 7. A sample project, showing the defauU Files Croup. 
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Test any application on any system 
Allows testing of remote systems 
Captures test resulte visually 
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The second group in tlie Groups & files pane is the Targm 
group, which weVe already discussed. The third group is yt>ur 
Executables group. By default, your project will contain a single 
executable (see the test executahie, shown in Figure 7). Note 
that when we upgraded our target in the Sketch projea, we also 
created a second executable, called Sketch (Upgraded). 

The next group is the Errors and Warnings group. Click on 
this group and the errors and warnings from your last liuild are 
shown, fjct's give this a try. In the Sketch project window, click 
and hold the first hammer icon in the toolbar, then select Build 
from the popup menu that appears. 

Figure 8 shows the result of my Sketch build. This build 
generated 2 warnings, both of them in the file 
SKTDrawDocument.m, and 1 error, in the file Sketcb_7nain.m 
(the warnings are actually part of the shipping Sbztch project, 
the error is one I purposefully introduced). If you click on the 
Errors and Warnings group iLscif, you1l see a list of all the 
errors and warnings in the projea. If you click on one of the 
file names in the group, you1l see a list of errors and warnings 
in that file. Finally, if you double-click on the Errors and 
Warnings group, you'll get a sepamic window with an upper 
split that iLsts all the errors and warnings in the projea, and a 
lower split that allows you to edit the source code associated 
with the selected error or warning. Basically, the project 
window without the Groups & files pane, 

ll\e Envrs & Warnings group is an example of what 
Apple calls a smart group. Smart groups are dynamic 
groups that change based on some aaion or rule. For 
example, the Em/rs & Warnings group is rebuilt each 
time you do a build. As you'll see when we get to the 
Find Results group a bit further along, smart groups are 
a very powerful part of Xcode’s arsenal. 
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Figure 8. The Errors and Warnings group. 


Next up is the Implementation files smart group, 'litis is an 
example of a rule-based smart group. To see what I mean, click 
on the Implementation files group and then click on the Show 


info panel icon (an italic i in a blue circle) in the toolbar or type 
command-i to bring up the inspeaor window. Rule-based smart 
groups can be generated using regular expressions or simple 
patterns. As you can see in the inspector window shown in 
Figure % the fnplementation files smart group searches the 
projea directory, recursively, to find aU files that match the 
regular expression: 

[ncHC] 

In effea, this regular expression matches any file name that 
ends in one of “.m”, “.c”, or placing the list of 
matching file names in the Implementation Files smart group. To 
learn more about regular expressions, check out tliis link: 

htlp://wvvw.grymoirexom/Unix/Regutar.html 

O'Reilly also has a book on regular expressions (is there 
needling they dtinl cover?) emailed Mastering Regular Expressions, 
^ Edition. 


When you click on the impkmmtation files group, if the 
main area does not change, bring up the inspector 
window (comniand-i), click in the Using Pailern: text 
field, and hit enter. That should force the list to update, A 
tiny glitch. Probably fixed already! 

O O Cfoup Mmpttmenui^ofi info CD 
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Save For: All My Projects 


A 

Figure 9. Ihe Implementaiion Files smart group, 
as seen in the inpectoK 
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Qt/Mac, che Mac OS X version of the Qt 
multiplatform C++ application framework, 
provides a uniquely unfair technological 
advantage in software development. Qt/Mac 
lets Mac developers develop in C++ on the 
platform they love most, while targeting 
additional operating systems, such as 
Windows or Linux. Qt/Mac also offers; 

■ fully object-oriented, elegant API 

■ single-source, multi platform development solution 

■ native compiling and applications that run at 
native speed 


■ integration with Project Builder, allow¬ 
ing developers to use Apple's own IDE 
for editing, compiling and debugging 
Qt/Mac applications 

■ OpenGL support, for sophisticated 3D 
graphics on the Mac 

■ native look & feel, such as the Aqua style 

Don't take our word for it. Visit us at 
www.troUtech.com/mac. Look at our list of 
Fortune 500 customers. Read what programmers 
say about Qt. Download the evaluation version, 
and see how easy C++ development can be. 
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The NIB smart group is just like tlie Implemeniation 
Files group, except it uses simple pattern matching instead of 
regular expression matching, returning ail files tliat match the 
simple pattern “**nib"- Smart groups are sweet. 

But they get even sweeter. Ihe Find Results smart group 
allows you to refine a search using the search field on the right 
side of the toolbar Here*s an example. Bring up the Sketcb 
project and select Find in Project., from the Find menu. Enter 
draw in the Find: field and check the Ignore Case checkbox, 
then click Find (see Figure 10). 


draw 

[ Textinl SwiAi 


I 

; Cdfltiins 

t si ^ Ignore Ca 


^ Jrt Preset 

l-f j laokinf in [ Ai Flits 

_ ^ 


( QncttI ^ t itgptoct StiecKd } # 

A 

Figure IQ, The Find in Projeci,., panel. 

A list of files should appear in the detail pane (the main part 
of die projea window) and the status bar (the thin horizontal 
strip immediately below^ the toolbar) should say 1 of 294 
selected. So our Bnd just found 294 occurrences of tlic word 
\lraw" in the project hierarchy. The results of this find were 
added to the Find Results smart group under the name draw. 

Now let's refine our search a bit. Click on die draw 
subgroup (it may already be selected). In the search field (right 


side of the toolbar), type the word "white”. You should see 2 
matches, for tfie function NSDrawWbiteBezel, both in 
SJCfGridView.m. You just did a search within a search. Very cooW 
Next on our list is the Project Symhoh smart group. Click on 
the Prqfecl SymMs group and a list of project symbols appears. 
As you might expect, you can use the search field to filter your 
symbols. If you click on the magnifying glass icon in the search 
field, a popup menu appears that lets you select from Search by 
All, Search hy Symbol, Search by Symbol Type^ and Search ty 
Location (these are tiie tliree column headers in the detail area). 
Pick the type of search you want to do, then start typing. In 
Figure 11, 1 did a Search hy Symbol Type and typed in "ma**. 
This reduced the symbol list to show the projecl macros. Nice! 
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Figure IL The Project Symbols group, with "ma" in the search 
Jield, and Search by Symbol Type selected in the 
search field popup menu, 









Till Next Month.,* 

IVe iK^cn using Xcode like crazy since WWDC and 1 find 
the design very intuitive. Xcodc does what J expect it to do. 1 
am impressed, and even more so given that this is prerelease 
software. Yes, there are a few bugs, but for me they Ve aO been 
minor. But be smart. 15e safe. Backup your projects before you 
port them to Xccxie, After all, prerelease is prerelease 

There are a few interface elements I'd like to see cleaned 
up. Some are simple refresh issues. Others are behavioral. For 
example, I'd like to see the little iriangie to the right of the 
magnifying gbLs.s icon in the search field only appear when there 
is a popup menu for that search field's context. And if there is a 
popup menu, how about including checkmarks next to any 
selected items so you can go back and see what die current 
settings are. Don) let these tiny nits deter you even one 
nanosecond, Xcode is an incredible leap forward. 

Before I go, just a few quick tilings. First, wheel over to 
http:y/developer.apple.com and check it out. They've completely 
redone the site. 1 find it much easier to navigate now, with a lot 
more detail on the front page. I also wanted to thank (profusely) 
the folks at Apple who spent so much time answering my Xcode 
and Cocoa questions. A special shout out to the folks who 
staffed the OS X and Tools labs at WWDC. You rock! 

Whelp, Fm out of space and out of time* Next month, we'll 
dig a little deeper into Xcode. There is so much more to cover. 
There's Code Completion. Zero Link, Fix and Continue, and 
Distributed Builds just to name a few. See you then...© 
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Selling, distributing and activating software 
electronically isn't new* But doing it securely 
AND all from one source certainly is newsl 
With Privilege from Aladdia you can have: 


Via the Internet; 

■ A secure ESO process, transforming casual 
sharing into a super distribution channel 
for triaiware 


m Increased customer satisfaction and loyalty 
with short and simple purchasing process 
and resumable downloads 


■ Instant access to international markets with 
multi-language support 


Via digital and CD: 

■ Your choice of CD's, or pre-loaded triaiware on 
new computers^ with flexible software activation, 
try-before-you-buy and try-only 

■ Capture new opportunities with full control over 
licensing terms, offers and the user's experience 


Take advantage of every new revenue 
opportunity available today! Call us at 
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PERL 


By Paul Ammann 

Perl Interprocess Communication 


This article will discuss the basic IPC facilities of Peri are 
built out of the good old Unix signals, named pipes, pipe opens, 
the Berkeley socket routines, and SysV IPC calls. Each is used in 
sliglitly different siaiations. 

Signals 

Perl uses a simple signal handling modeh the %SIG hash 
contains names or references of user-installed signal handlers. 
These handlers will l>e called with an argument which is the 
name of the signal that triggered it. A signal may lx? generated 
intentionally from a particular keyboard sequence like comrol-C 
or control-Z, sent lo you frtsm another prcx:ess, or triggered 
autoniatic’aliy by the kernel when sj^ecial events transpire, like a 
child prot:ess exiting, your process nmning out of stack space, 
or hitting file size limit. 

For example, to trap an interrupt signal, set up a handler 
like this. Do as little as you possibly can in your handler; notice 
how all we dt) is set a global variable md then raise an 
exception. Thafs because on most systems, libraries are not re¬ 
entrant; particularly, memory' allocation and I/O routines are not. 
That means that doing near ly anytliing in your handler could in 
theory trigger a memory fault and subsequent core dump. 

sub c3tch_2ap f 

my $3lauain^ - shiftj 
$ehucksf+: 

die "Stimebody sent me a STGlslgm^me": 

I' 

$STG I TNT I ^ ■ catc;h_zup' : ^ could fail in modiiJus 

$SiGlTNT! = \&c£itdj_i:ap: best sinitt'gy 

rhe names of the signals are the ones listed out by kilN on 
your system, or you can retrieve them from the Conftg module. 
Set up an ©signame list indexed by numljer to get the name and 
a %signo table indexed by name to get the number: 

use Config; 

defined $Conflglslg_natiie] || die "Mo sigs?"; 
foreacii {split {* \ SConf igi sig_naiiiel)) ( 

$signol$nanje} = $1: 

Ssignaste [$il = Sname; 

$i+f; 


So to check whether signal 17 and SIGALRM were the same, 
do just thist 

print "signal i/l7 “ $aignaTiia[17] \ti" : 
if [$slgna[ALRf1)) 1 

print "SIGALRM is $siBnolALRM]\n": 


You may also choose to assign the strings IGNORE’ or 
'DEFAIJT.T' as the handler, in which case Perl will try to discard 
the signal or do the default thing. 

On most Unix platforms, the CllLD (sometimes also known 
as CLD) signal has special behavior with respect to a value of 
IGNORE’. Setting $SrG|CHLDl to IGNORE’ on such a platform 
has the effect of not creating zombie processes when tiic parent 
process fails to waitO on its child processes (i,e, child processes 
are automaiically reaped). Calling w'altQ with $,SrGlCHLDl set to 
'IGNORE' usually returns -1 on such platforms. 

Some signals can be neither trapped nor ignored, such as 
the KILL and STOP (but not the TSTI^) signals. One strategy for 
temporarily ignoring signals is to use a locak) statement, w^hich 
will be automatically restored once your block is exited. 
(Remember that localO values are “inherited" by functions called 
from within that bkxk.) 

Bub precious \ 

local SSIGUNTI = * IGNORE': 

&jiiore_fmictiDns: 

1 

sub i3iore_functions ( 

* intetrupfs still ignored, for now,.. 

] 

Sending a signal to a negative process ID means that you 
send die signal to the entire Unix prcxTess-group, This code sends 
a hang-up signal to all processes in the current process group 
(and sets $S1G1HUP1 to IGNORE so it doesn't kiU itself): 

I 

local $SIG(I1UF) = ^IGNORE'; 
kill HUP => -S$; 

»snazzy writing of: lUP . -$S) 

I 


Paul Ammann has been the IT industry for 16 years, mostly recently working a,s a Network Security Engineer. He speaks UNIX as a second language. 
When he is not sitting in front of a computer, lie's planning the next vacation adventure with his wife Eve, 
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Another interesting signal to send is signal number zero. 
Tliis doesn't actually affect another process, but instead checks 
whether it's alive or has changed its IJTD. 

uDless (kill 0 => $kid„pid) t 

warn "something wicked happened to $kid_pld’': 

] 

You might also want to employ anonymous functions for 
.simple .signal handlers: 

SSIGIINT) = sub t die "\uOutta hera!\u'f h 

But dial will be problematic for the more complicated 
handlers that need to reinstall tliemselves. Because Perl’s signal 
mechanism is currently based on the signal(3) function from the 
C library, you may sometimes be so mlsfortunate as to run on 
systems where that function is '"broken", tliat is, it behaves in the 
old unreliable SysV way rather than the newer, more reasonable 
BSD and POSIX fashion. So yoy'll see defensive people writing 
signal liandlers like this: 

sub REAPER { 

$waitedpid “ wait: 

* loatht: sysV: i: makes us not only remstace 

# the handier^ but place it after the wait 
$SlGiCHLDf - \fiLREAFER; 

I 

$SIG1CIILD) = \&REAPER: 

# now do something that forks... 


or even the more elaborate: 

use POSIX ^;sys_walt_h": 
sub REAPER f 
my $chil<t: 

while {(Schild waitpid(-l,WNOKANG)) > 0) t 
$Kid_Statusr$childJ = 

1 

$SIG1CH1J}] “ \&RRAPER: # stUIloathe sysV 

) 

3SIG1CI1LD1 ” \6iREAPER: 

# do something that folks... 


Signal handling is also used for timeouts in Unix, While 
safely protected within an evallt block, you set a signal handler 
to trap alarm signals and then schedule to have one delivered 
to you in some number of seconds. Then try your blocking 
operation, clearing the alarm when it's done but not before 
you've exited your eva!(} block. If it goes off, you1l use dieO to 
jump out of the block, much as you might using longjmpC) or 
throwO in other languages. 

Here’s an example: 

eval i 

local $SIG[ALRM] = sub I die ’’alarm clock restart" I; 
alarm 10: 

f 1 0 ck C FE. 2): # blocking write lock 

alarm 0; 

h 

if ($@ and !“ /alarm clock restart/) [ die ) 
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If the operation being timed out is sy^;iemO or qxQi this 
technique is liable to generate zombies. If this matters to you, 
you'll need to do your own forkO and execC), and kill the errant 
child process. 

For more complex signal handling, you might see the 
standard POSIX module. Lamentably, this is almost entirely 
undoamienteci, but the t/lib/posix,t file from the Perl source 
distribution has some examples in it. 

Handling the SIGHUP Sigttal in Daemons 

A process that usually starts when the system boots and 
shuLs down when die system is shut down is called a daemon 
(Disk And Execution MONitor). If a daemon process has a 
conFiguration file which is modified after the process has been 
started, there should be a way to tell that process to re-read its 
configuration file, without stopping the process. Many daemons 
provide this mechanism using the SIGHUP signal handler. When 
you want to lell the daemon to re-read the file you simply send 
it the SIGHUP signal. 

Hot ail platforms automatically reinstall their (native) signal 
handlers after a signal delivery. This means that the handler 
works only die first time the signal is sent. The solution to this 
problem is to use POSIX signal handlers if available, their 
behavior is well-defined. 

The following example implements a simple daemon, 
which restarts itself every time the SIGHUP signal is received. 
The actvial code is located in the subroutine codeO, which 
simply prints some debug info to show that it works and should 
be replaced with the real code. 

#!/usr/bUi/pcri - w 

use POSIX (): 
use PindBln [); 
use File: :Basenaiiie f) : 
use File::Spec I:Functions I 

$ 1 = 1 : 

# tnake the daemon aoss-piatform.so exec always calls Uie script 

# iiself with ihe riglit path, nn matter how the script was invoked, 
my $ script = File: ;Basenama: :basenatiie($0) ; 

my $SELF “ eatflle ^FindEln::Bin, Sscfipt: 

# POSIX unmasks the sigprocmask properly 
my $sigset = POSIX::SigSet->new{): 

my faction = POSIX: rSigAction->rjew(*sigHtjP_handlei:\ 

$fiigSGt, 

iPOSIX::SA_NODEFER): 

POSIX;:sigaction(&FOSIX::SIGHUP. $actiDn): 

sub sigHUP_h3ndler I 

print *'got SIGHUP\n": 

exec($SELF, MRGV) or die "Couldn't restart: $I\n"; 

3 

codeO ; 

sub code I 
print 

print "ARGV; @ARGV\ii^ 
my $c - 0: 
while {++$c} [ 
sleep 2; 
print "Sc\n": 


) 

] 


Named Pu»es 

A named pipe (often referred to as a FIFO) is an old Unix 
iPC mechanism for processes communicating on the same 
machine. It works just like a regular, connected anonymous 
pipes, except that the processes rendezvous using a filename 
and don't have to be related. 

To create a named pipe, use the Unix command mkntjd(l) or 
on some systems, mkfifo(l). These may not be in your nomial path. 

# system return val is backwards, so not 11 

# 

$ENViPATHl ,= ^/etcr/uar/etc": 
if{system('rnknod',$path, 'p*) 

&& system{'tnkfifo'. Speth) ) 

( 

die "mklnod,flfol Spath failed": 

] 

A fifo is convenient when you want to connect a process to 
an unrelated one. When you open a fifo, the program will block 
until there's something on tlie otlier end. 

For example, lefs say you'd like to have your .signature file 
be a named pipe that has a Perl program on the other end. Now 
every Lime any pmgram (like a mailer, news reader, finger 
program, etc.) tries to read from that file, the reading program 
will block and your program will supply the new signature. Well 
use the pipe-checking file te.st -p to find out whether anyone (or 
anything) has accidentally removed our fifo. 

chdir: #goliomc 
$FIF0 “ '.signature': 

$ENV{PATH| .= ":/etc:/usr/gaiDeB": 

while (U [ 

unless (p $FIF0J t 
unlink $FrF0: 

systemUinknod*, $FIF0, 'p'] 

die "can't mknod $FIF0: $!": 

] 

# next tine blocks until there's a reader 

open (FIFO. ") $FTF0") || die "can't write $FIF0: $!"; 
print FIFO "John Smith (s]ivith\@host-org)\n". 'fortune s': 
close FIFO; 

sleep 2 :* to avoid dup signals 
I 


Deferred Signals 

In Peris before Perl 573 by installing Perl code to deal 
with stgnais, you were exposing yourself to danger from two 
thing.s. First, few system library functions are re-entmni. If the 
signal interrupLs while Perl is executing one function (like 
malloc(3) or printf(3)), and your signal handler then calls the 
same funaion again, you could get unpredictable behavior- 
often. a core dump. Second, Perl isn't itself re-entrant at the 
lowest levels. If the signal interrupts Perl while Perl is 
changing its own interna] data structures, similarly 
unpredictable behaviour may result. 
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There were two things you could do, knowing this: be 
paranoid or be pragmatic, l"he paranoid approach was to do as 
little as passible in your signal haodler. Set an existing integer 
variable that already has a value, and return. This doesn't help you 
if you're in a slow system call, which will fust restart. That means 
you have to die to longjumpC3) out of the handler. Even this is a 
little cavalier for the true paranoiac, who avoids die in a handler 
because the system is out to get you, 'ITie pragmatic approach was 
to say '1 know the risks, but prefer the convenience'", and to do 
anything you wanted in your signal handler, and be prepared to 
clean up core dumps now and again. 

In Perl 57.3 and later to avoid these problems signals are 
"deferred" — that is when the signal is delivered to the process 
by tlie system (to the C code that implements Perl) a flag is set, 
and the handler reairns immediately. Then at strategic "safe" 
points in the Perl interpreter (e.g. when it is about to execute 
a new opcode) the flags are checked and the Perl level handler 
from %SIG is executed. The “deferred" scheme allows much 
more flexibility in the coding of signal handler as we know Perl 
interpreter is in a safe state, and dial we are not in a system 
library function when the handier is called. However the 
implementation does differ from previous Peris in the 
following ways: 

Long running opcodes 

As Perl interpreter only looks at the signal flags when it about 
to execute a new opcode if a signal arrives during a long running 
opcode (e.g. a regular expression operation on a very large string) 
then signal will not be seen until operation completes. 

Interrupting lO 

When a signal is delivered (e.g. INT control-C) the 
operating system breaks intt) 10 operations like read (used to 
implement Peris o operator). On older Peris tire handler was 
called immediately (and as read is nor "unsafe" this worked 
well). With die "deferred" .scheme the handler is not culled 
immediately, and if Perl is using system's stdio literary that library 
may re-start the read without returning to Perl and giving it a 
chance to call tire %SIG handler. If this happens on your system 
tire solution is to use :perlio layer to do lO - at least on those 
handles which you want to be able to break into with signals. 
(The iperlio layer checks the signal flags and calls %S1G handlers 
trefore resuming 10 operation.) 

Note that the default in Perl 5.7.3 and later is to 
automatically use the :perlio layer. 

Signals as “faults" 

Certain signals e.g, SEGV, ILL, BUS are generated as a 
result of virtual memory or other "faults". These are normally 
fatal and there is little a Perl-level handler can do with them. 
(In panicular the old signal scheme was particularly unsafe in 
such cases.) However if a %SIG handler is set the new scheme 
simply secs a flag and returns as described above. This may 
cause the operating system to try the offending machine 


instruction again and - as nothing has changed - it will 
generate the signal again, ITie result of this is a rather odd 
"loop". In future Perl's signal mechanism may be changed to 
avoid this - perhaps by simply disallowing %SIG handlers on 
signals of that type. Until then the work-round is not to set a 
%S1G handier on those signals, (Which signals they are is 
operating system dependant.) 

Signals triggered by operating system state 

On some operating systems certain signal handlers are 
supposed to "do something" before reaiming. One example can 
be CHLD or CLD wliich indicates a child process has completed. 
On some operating systems the signal handler is expected to 
wait for the completed child process. On such systems the 
deferred signal scheme will not work for those signals (ir does 
not do the wait). Again the failure will look like a loop as tlie 
operating system will re-issue the signal as there are im-waited- 
for completed child processes. 

Using openQ for IPC 

Peri's basic openO statement can also be used for 
unidireaional interprocess communication by either appending 
or prepending a pipe symbol to the second argument to openO- 
Here's how to start something up in a child process you intend 
to write to: 

opentSPOOLER. "| cat -v | Ipr -h 2>/dev/null’') 

I I die ’’can't fotk: $1 ”: 

local $SIG[PIPE1 = sub [ die "spooler pipe broke" 1: 

print SPOOLER "stuff\n": 

close SPOOLER || die "bad spool: $! 

And here's how to start up a child process you intend to 
read from: 

open(STATUS* "netstat an 2>&1 |") 

II die "can't fork: $1": 

while (<STATUS)) [ 

next if /'^(tcp|udp) / : 
print; 

1 

close STATUS II die "bad netstat: $1 $?": 

If one can be sure that a particular program is a Perl script 
that is expeaing filenames in @ARGV, the clever programmer 
can write something like this; 

% progreni fl "cmdl|" - f2 "c(nd2|" fl < tinpfile 

and irrespective of which shell it's called from, the Perl 
program will read from the file/i, the process cmdl, standard 
input (tmpfile in this case), the f2 file, the cmd2 command, and 
finally the J3 file. Pretty nifty, eh? 

You might notice that you could use backticks for much the 
same effect as opening a pipe for reading: 

print grep ( l/''(tcp|udp)/ 1 "netstat -an 2>&P: 
die "bad netstat" if $7; 


18 


Perl Interprocess Communication 


MacTech • August 2003 







while this is true on the surface, it's much more efficient to 
process the file one line or record at a time because then you 
don't have to read the whole thing into memory at once. It also 
gives you finer control of the whole process, letting you to kill 
off the child process early if you'd like* 

Be careful to check both ilie openO and the closeO 
return values. If you're writing to a pipe, you should also 
trap SIGPIPE. Otherwise, think of what happens when you 
Stan up a pipe to a cofiunand that doesn't exist: the openO 
will in all likelihood succeed (it only reflects the forkO's 
success), but then your output will fail—spectacularly. Perl 
can't know whether the command worked because your 
command is actually running in a separate process whose 
execO might have failed* Therefore, while readers of bogus 
commands return just a quick end of file, writers to bogus 
command will trigger a signal they'd better be prepared to 
handle. Consider: 

open(FH, 'Jbogus’’)or die “can't fork: $1": 
print FH ’’bangVn’’ or die "can’t write: $l"t 
close FHor die “can't close: $!”: 

Thai won't blow up until the close, and it will blow up with 
a SIGPIPE, To catch it, you could use this: 

$SIG{PIFE) - ’IGNORE': 

open{yH, "Ibogus")or die "can't fork: $1"; 
print FK “bangAn" or die “can’t write: $f*: 
close FHor die "can't close; status“$7“: 


and to /dev/null (so tiiat random outpui doesn't wind up on the 
user’s tetminalX 

use POSIX ‘setsld*: 
sub daemonIze I 

chdlr ‘7' or die "Can't chdlt to /: Sr“; 

open STDIK, ’/dev/null'or die *Can’t read /dev/null: $1": 
open STDOUT* *>/dev/null' 

or die "Can’t write to /dev/nuil: $[": 
defined[my $pid “ fork) or die “Can't fork: $!": 
exit if $pid: 

setsid or die "Can't start a new session: $!"; 

open STDERR. '>iSTl}OUT’ or die "Can't dup stdout: $!": 

I 

The forkC) has to come liefore the setsidO to ensure that 
you aren't a process group leader (the seLsidO will fail if you 
are). If your system doesn't have the setsidO function, open 
/dev/lly and use the TIOCNOTTY ioctlO on it instead* See tti<4) 
for details. 

Non-Unix users should check their Your_OS::Prrx:ess 
module for other solutions. 

Safe Pipe Opens 

Anotfier interesting approach to IPC is making your single 
program go multiprocess and communioie iietween (or even 
amongst) yourselves, Ihe openC) function will accept a file 
argument of either or to do a very interesting thing: it 
forks a child connected to the filehandle youVe opened. 'Fhe 


Filehandles 

Both the main prtKess and any child processes it forks 
share the same STDIN, S'rOOUT, and STDERR filehandles. If 
both processes try to access tliem at once, strange things can 
happen. You may also want to close or reopen the filehandles 
for the child, Ycju can get around this by opening your pipe wiiit 
openOj but on some systems lliis means that the child process 
c-annot outlive the parent. 

Background Processes 

You can run a command in the background with: 

system("cnid &"): 

The command's STDOUl' and STDERR (and possibly 
S'lDIN, depending on your shell) will be the same as the 
parent's. You won't need to catch SIGCHLD because of the 
double-fork taking place (see below for more details). 

Complete Dissociation of Child from Parent 

In some cases (starting server processes, for instance) you1l 
want to completely dissociate the child process from the parent. 
This is often called daemonization. A well behaved daemon will 
also chdirO to the root directory (sr) it doesn't prevent 
unmounting tlie filesystem containing the directory from which 
it was launched) and redirea its standard file descriptors from 
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child is nifining the same program as the parciiL Tiiis is useful 
for safely opening a file when running under an assumed UtD 
or GID, for example. If you open a pipe to minus, you can write 
to the fikhandle you opened and your kid will find it in his 
STDIN. If you open a pipe from minus, you can read from the 
filehandle you opened whatever your kid writes to his STDOUT. 

use English ‘-no_tDatch_vars': 
ay $sleep_count “ 0; 

do I 

$pid - open(KII>_TO_WRITE. 
unless (defined $pid) i 

warn "cannot fork: $!”; 

die "bailing out" if $sleep_countH- > 6: 

sleep 10: 

I 

} until defined $pid: 

if C$pid) t # parent 

print KTD^T0_WR1TE @some_data: 
clDseCKID_TO_WRITE) \\ warn "kid exited S?"; 

] else t # child 

($EUID. $ECID) » ($UTD* SGID): *suid pn>gs onty 
open (FILE, "> /safe/file") 

II die '^can't open /safe/file: $1"; 
while (<STIHN>) { 

prim Fn.E;^ child’s STDIN is parent's KJD 

I 

exit:* don't fbr^t this 

) 


Another common use for this coastruct is when you need 
to exeaiie something without the shell's interference. Widi 
systemO, it's straightforward, hut you can’t use a pipe open or 
backticks safely. That's because dierc’s no way to stop the shell 
from gening its hands on your aiguments. Instead, use lower- 
level LX)ntrol TO call execO directly. 

Here's a safe backtick or pipe open for read: 


* add error procc^i!iing 3S above 
$pid * open(KTD_TO_READ. 

if {$pid) [ ^parent 

while [<KID_TO_READ>) I 
* do sotnctlihiR intcresunf* 

closetKID_TO„READ) [| warn “kid exited S?“: 
} else ( * child 

$EUID< $EGID) - ($Uin. fitsuidonly 

exec (Sprogracn. @Dpcions, §args) 

II die "can*t exec program: $1"; 
*NOTREACHe) 


And here's a safe pipe open for writing: 

* add cnor processing above 

$pid “ openCKI0_.T0_WHlTE. “h"): 

$SIG{P1PEI = sub [ die "whoops, Sprogtaai pipe broke" ): 

if ($pld ) i * parent 
for (§data} t 

print ICID„TO„tfRTTE: 

1 

close(KID_TO_yRITE) [| warn "kid exited $?": 

} else ( * child 

C$EUID, $EGID) - ($UID. $GTD); 
exec(^program. @optlonfi. dargs) 

II die “can’t exec program: S!”: 

# NOTREAaiED 


Since Peri 5^B^0, you can also use the list fonn of open for 
pipes : the syntax 

open KID_PS, "d"- "ps". "aux" or die $1: 

forks the ps(l) command (widioui spawning a shell, as 
there are more tlian tfiree arguments to openO), and reads its 
standard output via the KID_PS filehandle. The corresponding 
syntax to read from cTommand pipes (with " | in place of1") 
Ls also implemented. 

Note that these operations are full Unix forks, wliich means 
they may nt>i be correctly implemented on alien systems. 
Additionally, these are not true multithreading, ff you’d like to 
learn more about tlireading, see the modules file mentioned in 
the SEE ALSO section, 

Bidirectiofiai Communicatitm with Another Process 

While this works reasonably well for unidirectional 
communication, what about bidirectional cximmunication? The 
obvious thing you'd like to do doesnT actually work: 

open{FROG_FOR_READIHG_AND_tfRTTTNG» •] some program |“I 

and if you foiget to use the use warnings pragma or the -w 
flag, then you1l miss our entirely on the diagnostic message: 

Gait't do bidirectional pipe at -e line 1. 

If you really want to, you can use the standard open2() 
library function to catcli both ends. There's also an open3() 
for Iridirectional I/O so you can also catch your child’s 
SIDERR, but doing so would then require an awkward 
selectO loop and wouldn't allow you lo use normal Perl 
input operations. 

If you Itxik at its source, youll .see that open2{) uses low- 
level primitives like Unix pipeO and execO calls to create ali the 
connections. While it might have been slightly more efficient by 
using sockcipairf), it would have dien been even less portable 
than it already is. The Qpen20 and open3C) funaions are 
unlikely to work anywhere except on a Unix system or st^me 
other one purpt)rting to l^e POSIX compliant, 

Here's an example of using open2{): 

use FtleHandle: 
use TPC::0peu2: 

Spld ** open2UReflder* ‘Writer* “cat *u *n" ): 
print Writer 
$got “ <Reflder>; 

The problem with this is that Unix l>uffering is really going 
to ruin your day. Even though your Writer filehandle is auto- 
flushed, and the process on the other end will get your data in 
a timely manner, you can’t usually do anything to force it to give 
it back to you in a similarly quick fashion. In this case, we could, 
because we gave cat a -u flag to make it unbuffered. But very 
few Unix commands are designed to operate over pipes, so this 
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seldom works unless you yourself wrote the program on the 
other end of the double-ended pipe. 

A solution to this is the nonstandard Comm.pl lil>rary. It 
uses pseudo-ttys to make your program more reasonably; 

require ’CoaHE.pl*: 

Sph ^ open_proc £ ‘ eat - n *); 
for (1..10) t 

print $ph *^3 lineVn": 

print ”got back scalar C$ph); 

1 


Ihis way you don't have to have control over the source 
code of the program youVe using. The Comm library also has 
expectO tind interactO hinctions. Find the library (and I ho|>e its 
successor IFCr.Cbat) at your nearest CPAN archive. 

The newer Expect.pm module from CPAN also addresses 
tliis kind of thing. 'Phis module requires two other modules from 
CPAN; IO::Pty and IO::Stty. It sets up a pseudo-terminal to 
interaa with programs that insist on talking to the terminal 
device driver. If youi system Ls amongst those supported, this 
may be your l>est bet. 


Bidirectional Commuiiicalion with Yourself 

If you want, you may make low-level pipeO and forkO to 
stitch this together by hand. This example t>nly talks to itself, but 
you could reopen die appropriate handles to STDIN and 
STDOirr and call other prtKCsses. 

#!/itsf/bin/perl -w 

* pipcl' bidirecTbii^l communicaiiori ujiinf; two pipe pairs 
» designed lof the sockcipairchallcnged 

use I0::Handle; # thousands of lines just foe autofluah : ( 
pipe (PARENT^RDR, CHILD_WTH) : # XXX; failure? 
pipetCHlLD_RDR.FMENT^WTR) : ffXXX:failure? 

CHILD_^WTR->autoflush(l); 

PAREMT_WTR->autofIushCl); 

if ($pid - fork) [ 

close PARKHT^RDR: close PARENT.WTR; 
print CH1LD_WTR "Parent Pid $$ Is sending 
chomp (Sline <CHILI5_RDR>) r 

print "Parent Pid $$ Just read this: '$llne'\n“: 
close CKILD^RDR: close CHItD_WTR; 
waitpid($pid.O): 

I else I 

die "cannot fork; $1" unless defined $pid: 

close CHILO^RDR; close CHILD.WTR: 

choiipt$line “ <PARENT_RDF>): 

print "Child Pid S$ Just read this: 

print PAREIfT_WTR "Child Pid $$ is sending thls^n'’: 

close PARENT^RDR: close PARENT_WTR: 

exit; 

» 


But you don't actually have to make two pipe calls. If you 
have the socketpaiil) .system call, it will dtJ this all for you. 

*!/uar/hin/pt*fl W 

* pipe2 * NdirecUonaJ cominutiicaiinn usiitg sockeipair 

* *thc best ones always go both ways^ 

use Socket; 

use 10Handle; # thousands of lines [iM for autoflnsh 

# We say AFJIfTO because although "_LCxi\L ts the 

# POSDC 1003- Ig fonn of the consiantp many raachiocs 
^ still don't haw it. 

socketpair(CHIJJ3> PARENT, AF^UNIX, SOCICSTREAH, PF_UNSPEC) 


or die "socketpair: $!"; 

CHILD'>autoflush£l): 

PARENT“>autoflush(l); 

if [$pid = fork) t 
close PARENT: 

print CHILD "Parent Pid $$ is sending thisAn"; 
chompC$line “ <CHILD)): 

print "Parent Pid $$ Just read this: '$lina'\n": 
close CHILD; 
waitpid($pid*0); 

I else i 

die "cannot fork: $!" unless defined $pid: 
close CHILD: 

chomptSline <PARENT>); 

print "Child Pid just read this: '$line'\n": 

print PARENT "Child Pid $$ is sending thisVn": 
close PARENT; 
exit; 


SOCKLTS: CliEIST/SERVFR COMMlilSlCATlON 

While not limited to Unix^lerived operating systems (e,g., 
WinSock on PCs provides socket support, as do some VMS 
libraries), you may not have sockets on your system, in which 
case this section proliably isn’t going to do you much good. With 
sockets, you can do both virtual circuits (Le., TCP streams) and 
datagrams (i.e., UDP packets), You may be able to do even more 
depending on your system. 

Tlie Perl funaion calls for dealing with sockets have the same 
names as the corresponding system calls in C, but their arguments 
tend to differ for two rcusons: first, Perl fileliandles work differently 
ilian C file descriptors. Second, Perl already knows the length of 
its strings, so you don’t need to pass that information. 

One of the major problems with old socket code in Perl was 
tliat it used hardcoded values for some of the constanLs, which 
severely hurt portability. If you ever see code that does anything 
like explicitly setting $AF_INL1'« 2, you know youYe in for big 
trouble: An immeasurably superior approach is to use the Socket 
module, which more reliably gninUs access to various constants 
and functioas you'll need. 

If you're not writing a server/client for an existing protocol like 
NNTP or SMTP, you should give some thought to how your server 
will know wiien the client has finished talking, and vice-versa. Most 
protocols are based on one-line messages and respoases (so one 
party knows the other ha,s finished when a “\n" is receivecD or 
multi-line messages and responses tliat end with a period on an 
empty line (“\nAn” terminates a m^sage/response). 

Internet line Terminators 

'the internet tine terminator is ‘'\015\012A Under ASCU 
variants of Unix, that could usually be written as “\r\n”, but 
under other systems, “\r\n” might at times be 
“\012\012\015*‘, or something completely different 'The 
standards specify writing *‘\015X012'' to be conformant (be strict 
in wfial you provide), but they also recommend accepting a lone 
'*\012” on input (but be lenient in wliai you require). We haven't 
always been very gocxl about that in the code In this manpage, 
but unless youTe on a Mac, you’ll probably be ok. 
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Internet TCP Clients and Servers 

Use Internet-domain sockets when you want to do client- 
server communication that might extend to machines outside of 
your own system. | 

Here’s a sample TCP client using Intemel-domain sockets: 


•l/usr/bin/peri 'W 
xifie strict: 
use Socket: 

my (^remote,Sport. Siaddr, Spaddr^ Sptoto. $line); 

Sremote” shift || ‘iocalhost*: 

$pott= shift I I 2345:# random pOft 

if export /\D/) [ Sport = getservbyname(Sport» 'tep') ) 
die "No port" unless Sport: 

Slatjdr “ inet_a touts remote) [1 die *no host: Sremote"; 

Spaddr = sockeddr_in(Sport* Siaddr): 

Sproto " getprotobynamet'tep'); 

socket(SOCK* PF^INET, SOCK^STREAM* Sproto)|| die ^socket: St": 
connect (SOCK, Spaddr) 11 die ^connect: SI"'; 
while (defined($line - <S0CK>n t 
print Sline: 

I 

close (SOCK)[I die "close: St"; 
exit: 


And here's a corresponding server to gc) along with it. Well 
leave the address as 1NADDR_ANY so that the kernel can 
chcKWiC the appropriate interface on multihomed hosts. If you 
want to sit on a particular interface (like the external side of a 
gateway or Firewall machine), you should fill this in with your 
real address instead. 



*!Aisr/!Mn/pcri 

use strict: 

BEGIN ( $ENVIPAX01 = */usr/ucb:/bin' 1 
use Socket: 
use Carp: 

my $EOL - -\015\012": 

sub logmsg I print $5: at scalar localtima. "Vn" J 

ray $port = shift || 2345: 
my $proto * getprotobynaraet‘tep'): 

(Sport) ^ Sport /*C\d+)$/or die "invalid port": 

fiOcket(Server, FF_mET, SOCK^STREAN* Sproto) 11 die "socket: $1"; 
setsockopt(Server, SOL^SOCKET, SO_ilEUSEADDI, 
pack(*l*, 1)) 11 die "setsockopt: $!": 

bind(Server. sockaddr_ln(Sport. INADDILANYJ)|| die "bind: $1": 
llsten{Server.SOMAXCONN)i| die "listen: Sl"i 

lograsg "server started on port Sport"; 

my Spaddr: 

SSIGICHLDI “ \4K£APER: 


for ( ; Spaddr “ accept(Client.Server): close Client) I 
my (Sport.Siaddr) = sockaddr.ln(Spaddr): 
my Sname “ gethostbyaddr(Siaddr.AF_INET): 

logmsg "connection from Sname 
inet_ntoa(Siaddr), "J 
at port Sport": 




print Client "Hello there, Sname, it's now ", 
scalar locaitime, SEOL; 
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And here's a multihomed version. It's multithreaded in that 
like most typical servers^ it spawns (forks) a slave server to 
handle the client request so that the master server can quickly 
go back to service a new client. 


^l/usT/bin/perl -Tw 
uae strict I 

BEGIN ( SENVIPATH) = '/uBr/ucb:/bln' ) 

u$e Socket: 
use Car[}: 

my SEDL = ■\015\012*; 
sub spawn; * forward dechrsdon 

sub logmsg 1 print "$0 $$; at scalar localtime* "Vn” J 

my $poi:t - shift || 2145: 
my $proto getprotobyn«me(‘tcp’): 

(Sport) “ Sport =- /*{\d+)$/or die "invalid port"; 

socket(Server* PF_rNEr* SOCiLSTREAM. Sproto)|j die "socket: $1": 
setfiockopttServer, S0L_S0CKET* SO^REUSEADDR. 

packl"!", 1)} II die "setsockopt: Si": 

bind(Server. sockaddr.in(Sport* TNADDRJ^Y)J11 die "bind: SJ": 
listen{Server.S0MA5tC0m[| die "listen: $*": 

lognsg "server started on port Sport": 

my Swaitedpid 0: 
my Spaddr: 

use POSIX -ssys.waiO*; 
sub REAPER I 
my Schild: 

while ((Swaitedpid " waltpidC l.WNOKANG)) >0) J 

lognisg "reaped $waltedpid" *[$??" with exit S?" : "): 

SSIGICHLDI - \tREA?ER:«!^]oaihcsysV 


SSIGiCHLD* - \&REAPER: 


for ( Swaitedpid * 0: 

(Spaddr “ accept{CUent,Server)) j | Swaitedpid; 
Swaitedpid = 0, close Client) 

1 

next if Swaitedpid and not Spaddr: 
my(Sport.Sladdr) = sockaddr_io(Spaddr): 
my Sname " gethostbyaddr($laddr.AP_1NET); 

lograsg "connection from Sname I\ 
lnet_ntoa(Siaddr), "J 
at port Sport": 


spawn sub [ 

S|-i: 

print "Hello there, $name, it's now ", scalar 
localtime, $E0L: 

exec */usr / game s/fortune'' # XXX:' wrong' line termlnitorj 
or confess "can't exec fortune: $t": 


I 


sub spawn ( 

my Scoderef * shift: 

unless (®_ — 0 Scoderef ^th ref (Scoderef J eq 'CODE') ( 
confess "usage: spawn CODEREF"; 

) 

my Spid: 

if (!defined(Spid “ fork)) I 
logmsg "cannot fork: $!": 
return: 

I elsif (Spid) ( 

logmsg "begat Spid": 
r etu r n 1 *Vm the parcnc 

* else J'm the child - go spawn 


openCST0IN,"<5tClient") |[ die "can't dup client to stdln": 
openiSTDOtlT, ">&Cllent") | | die "can't dup client to 
stdout": 

# open(STDERR* ">iSTD0UT*) || die "can^t dup stdout to 
stderr": 

exit &Scoderef(): 


This server takes the trouble to done off a child version via 
forkC) for each incoming request, Tbat way it can handle many 
requests at once, which you might not always want. Even if you 
don't forkO, the listenO will allow that many pending 
connectioas. Forking servers have to be particularly careful 
about cleaning up their dead children (called “zombines'' in 
Unix parlance), because otherwise you'll quickly fill up your 
process table. 

I suggest that you use the -T flag to use taint checking even 
if we aren't running seiuid or setguid. This is always a good idea 
for servers and other programs run on behalf of someone else 
(like CGI scripts), because it lessens the chances that people 
from the outside will be able to compromise your system. 

Let's look at another TCP client. 'Ibis one connects to the 
TCP “time” service on a number of different machines and 
shows how far dieir clock differ from the system on which it’s 
being run: 


♦lAisr/tai/peil-w 
use strict: 
use Socket: 

my $SECS_qO0^YEARS - 2208988300: 
sub ctime ( scalar localtiMcCshift) 1 

my $iaddr = gethostbynaine t' localbost'): 
my Sproto = getprotobynameCtep'): 
my Sport " getservbynamet'time'. 'tep'): 
my Spaddr “ sockaddr_ln£0, Siaddr): 
mytShost); 

$1 - 1 : 

printf •»' 24 s X 8 s XsVn*. nocalhost". 0 . ctiiie(tiBeC)): 

foreacb Shost CftAROV) { 

printf "* Sboat; 

my Shisiaddr ■ inet_aton[Sboet) || die "unknown host": 
my Sbispaddr “ 80ckaddr_ln{Sport. Shisiaddr): 
socket(SOCKET* PF_INET* SOCOTREAM* Sproto) |j die 
"socket: Si": 

connect(SOCKET* Shispaddr)|[ die "bind: Si*; 
my Srtime “ 

read(SOCKET* Srtime. 4): 
cloae(SOCKET): 

my Sbistime “ unpack("N". Srtime) - SSECS_of_70_YEARS ; 
printf "%8d Shistltne ■ time, ctime(Shlstirae): 


Unix-Doniam TCP Clients and Servers 

That’s fine for Iniernet-domain clients and servers, but what 
alx)ut local communicaiions? While you can use the same setup, 
sometimes you don't want to. Unix-domain sockets are local to 
the current host, and are often used internally to implement 
pipes. Unlike Internet domain sockets, Unix domain sockets can 
show up in the file system with an ls(l) listing. 

% Iff -1 /dev/log 

srw-rv-rw- 1 rootO Oct 31 07:23 /dev/log 
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unless (8_ = 0 && $coderef refC$coderef) eq 'CODE') 


You can test for these with Perl's -S file test: I 

unless ( -S */dev/lo§' ) { 

die "soaiething's wicked with the leg system'*: 


Here’s a sample Unk-domain client: 

*!Aisr/btn/pcri -w 
use Socket; 
use strict: 

my ($ rend e 2 vo us, $1ine J; 

$rendezvous " shift || */tmp/catsock‘; 

soqket(SOCK. PF_UNIX. SOCiLSTEEAM. 0) j| die '’socket: $r: 
connect{S0Ck, sockaddr_un{$i:endezvoiis) J || die "connects SI**: 
while (defined(Sline " <S0CK>)) ( 
print Slide; 

I 

exit; 


confess "usage: spawn CODEREF": 

I 

my $pid; 

if 0defined(Spid = fork)) t 
logmsg "cannot fork: Si"; 
return: 

1 elaif (Spid) ( 

logmsg "begat $pid''; 
return; »Fm thepatcni 
I 

^ ctsc Fm the child ^ go Stpawn 

open(STDIN< "XiClient") || die *'can‘t dup client to 
stdin": 

open(STDOUT» ''>&Client") || die "can’t dup client to 
stdout": 

# openCSTDERR* ■'>£tSTDOUT“) | | die "can't dup stdout to 
stderr"; 

exit h$coderef(); 

1 


And here’s a corresponding server You don't have to worry 
about silly network terminators here because Unix domain 
sockets are guaranteed to be on the localhost, and thus 
everything works right. 

#!/usr/bin/pCTl -Tw 
use strict; 
use Socket; 
use Carp; 

BEGIK ( SEUVfPATH) = 7usr/uch:/bln' 1 
sub spawn; # forward declaration 

sub logmsg I print "$0 $$: at ", scalar localtlme, "\n" 1 

my SNAME '/tmp/catsock’; 
my Suaddr * sockaddr_un(SNAKE); 
my Sproto * getprotobynamef*tcp'); 

socket(Server,Pr„UHTX.SOCK_STREAM,0)I) die "socket: $!•; 
unlink(SNAME): 

bind (Server. Suaddr) || die "hind: $!": 
llsten(Server,SOMAXCONN)|I die "listen: $1": 

logmsg "server started on SNAKE"; 

my Svaitedpid; 

use POSIX ":ays^wa^O^ 
sub REAPER [ 
my Schlld; 

while ((Swaitedpid « vaitpid(-1.WNOHANG)) > 0) ( 

logmsg "reaped Swaitedpid" . ($? T " with exit $7" ; 

\ 

$SIG(CHLDJ - \&REAPER; # loathe sysV 

} 

SSIGICHLD) ‘ \&REAPER: 

for ( Swaitedpid = 0; 

accept(Client.Server) || Swaitedpid: 

Swaitedpid ~ 0, close Client) 

( 

next if Swaitedpid; 

iogmsg "connection on SNAKE"; 

spawn sub { 

print "Hello there, it's now "* scalar localtime. 

"\n"; 

exec '/usr/games/fortune* or die "can't exec 
fortune: $}"; 

h 

1 

sub spawn I 

my Scodetef = shift; 


As you see, it's remarkably similar to the Internet domain 
TCP server, so much so, in fact, that weVe omitted several 
duplicate functions-spawnO, logmsgO, ctimeO, and REAPERO- 
which are exactly the same as in the other server. 

So why would you ever want to u,se a Unix domain socket 
instead of a simpler named pipe? Because a named pipe doesn't 
give you sessioas. You can’t tell one process’s data from 
another's. With socket programming, you get a separate sessitin 
for each client: that's why acceptO takes twt> arguments. 

For example, let's say chat you have a long running 
database server daemon that you want folks from the World 
Wide Web to be able to access, but only if they go through a 
CGI interface. Yc^u’d have a small, simple CGI program that does 
whatever checks and logging you feel like, and then acts as a 
Unix-domain client and connecls to your private server. 

TCP CtJENTS WITH lOnSOCKET 
For those preferring a higher-level interface to socket 
programming, the 10::Socket module provides an object- 
oriented approach. 10::Socket is included as part of the standard 
Perl distribution as of the 5,004 release. If youTe running an 
earlier version of Perl, just fetch IO::Socket from CPAN, where 
you'll also find mtxlules providing easy interfaces to the 
following systems; DNS, FTP, Ident (RFC 931), NIS and NISPlus, 
NNTP, Ping, POP3, SATIP, SNMP, SSLeay, Telnet, and Time-just 
to name a few. 

A Simple Client 

Here's a client that creates a TCP conneaion to the 
'‘daytime" service at port 13 of the host name “localhost" and 
prinLs out everything diat die server there cares to provide, 

*!/usr/bin/pcri -w 
use 10;:Socket; 

$remote * 10;: Socket:: INET‘>iiew( 

Proto^> "tep". 

PeerAdi3r => "localhost". 

PeerPort => "daytime(13)", 

or die "cannot connect to daytime port at 

localhost": 

while ( <$teiiote> ) I print J 
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When you run ibis program, you should get something 

back that looks like this: 

Wed May 14 08:40:46 KDT 1997 

Here are what those parameters to the new coa^aor mean: 

• Proto * This Is which protocol to use* In this case, the socket 
handle returned will be connected to a I'CP socket, because 
we want a stream-oriented connection, that is, one that acts 
pretty much like a plain old file. Not all sockets are this of 
this type. For example, the UDP protocol can be used to 
make a datagram socket, used for message-passing. 

• PeerAddr - This Ls the name or internet address of the remote 
host the server is running on. We could have specified a longer 
name like 'Vww.perixom", or an address like "204.148.40.9”. 
For demonstration purposes, we’ve used die special hostname 
"localhost", whidi should always mean the current machine 
you're rumiing on. The corresponding Internet address for 
localhost is "127*1", if you'd rather use that. 

• PeerPort - This is the service name or port number we’d 
like to connect to. We could have gotten away with using 
just Maytime” on systems with a well-configured system 
services fileJFOOTNOTE: Ihe system services file is in 
/etc/services under Unix] but just in case, weVe specified 
the port number (13) in parentheses* Using just the number 


would also have worked, but constant numbers make 
careful programmers nervous. 

Notice* how the return value from the new constructor is 
used as a filehandJe in the while loop? Thafs whafs calJed an 
indirect filehandle, a scalar variable containing a filehandle. You 
can use it the same way you would a normal filehandle. For 
example, you can read one line from it this way: 

$llne =" <$handic>i 

all remaining lines from is this way: 
eiines <$handle>r 

and send a line of data to it this way: 

print $hand1e "some dataVa*^: 

A Webget Client 

Here's a simple client that takes a remote host to fetch a 
document from, and dien a list of dcK'uments to get from that 
host. This is a more interesting client than the previous one 
because it first sends something to the server before fetchuig the 
server's response. 
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users. Addresses that have been sent auto-reply messages are 
tracked, preventing auto-reply message loops. Demo available. 
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Fast and powerful utility for sorting and cleaning email lists. Sort 
email address lists in alphabetical or domain order, remove 
duplicates and improperly formed addresses. Demo available. 
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Jl/lae OS X Killer rips by Scott Keiby $19.95 Have you ever had a buddy ask iF you 

"want to know an easy way to do that?" They lean over your keyboard, click a Few keys and you learn an 
undocumented keyboard shortcut, □ cool hack, a hidden system option, or just a cleaner way to get the job 
done. With Mac 05 X, most oF our favorite tricks are gone - if s a whole new game. This 288 page book 
is cover to cover tips and tricks For getting the most out of Moc OS X paguar). 


Mac OS X Disaster Relief by Ted Landau $19.95 The unexpected will happen, 

sometimes you*I! need more than o manual, _MacOS X Disaster RelieL is the first trouble shooting guide to 
Mac OS X, written by Ted Landau (Founder of MacFixIt), This book includes information about Mac OS X‘s 
invisible files, third party troubleshooting tools, the smart way to install (or re-install) Mac OS X - plus tips, 
tricks, and troubleshooting techniques. 



Cocoa Programming by Scott Anguish, Erik Buck & Donald Yacktman $39.95 Over 1200 

pages the most comprehensive Mac programming book available for the new Cocoa API. Not for beginners, 
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The Wh'eless Networking Stmter Kit by Adam Engst & Glenn Fleishmon $24.95 
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permissions, administration, firewalls, and others. At some point, you will wont this reference. 

Mac 05 X for Unix Geeks by Brian Jepson, Ernest E. Rothman $16.95 Mac OS X has 

a BSD core* If s a heady feeling to have the power and flexibility of UNIX on Macintosh, but if you are a 
UNIX guy you'll find there are some subtle differences. This book is a solid reference, to help you make the 
switch. It shows you everything from your familiar user shells and directory services to building applications 
and system management - and how each is done under OS X 10.2 (Jaguar). 


Mm 05 X Hades by Rael Dornfest, Kevin Hemenway $16.95 Mac OS X presents a unique 
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pages, pulling the best tips, tricks, and tools from the Mac power users and Unix hockers themselves. 


Cocoa Recipes for Mac 05 X by Bill Cheeseman $29.95 A step by step how-to on 

building an application with Apple's Cocoa framework. The 21 individual recipes, over 750 pages, walk 
you through the process of building a single, industrial strength application - while illustrating essential topics 
like handling menus, windows, data storage, user preferences, drog and drop, tables, undo/redo, and more. 
Want to get started with Cocoa? This is the book. 












»?/usr/bin/pefl -w 
use 10:iSocket; 

unless (9AkGV > 1) ( die "usage: $0 host document } 

$host = shift(@ARCV): 

$E0L = "\015\012": 

$BLANK - $EOL x 2; 

foreach Odocuinent ( #ARGV ) f 

Sremote = 10:: SocketINET->iiew( Proto -> "tcp" 

PeerAddr ihost, 

pearPort "> "httpC&O}", 
): 

unless (Sremote) I die "cannot connect to http daemon on 
$ho8t" 1 

$ remote'>autoflush{1 ^: 

print $reiiiote "GET $docuiietit mP/1,0" . ^BLANK: 
while ( <$r€iiiote> ) I print I 
close $remote; 

I 


The web server handing the "http” service, which is assumed 
to be at its standard port, number 80. If the web server youTe 
trying to conoea to is at a different port (like 1080 or 8080), you 
should specify as the named-parameter pair, PeerPon 8080. 
'fhe autoflush metfiod is used on the socket because otherwise 
the system would buffer up the output we sent it. (If you're on a 
Mac, you'll also need to change every "\n" in your code that 
sends data over the network to be a ^\015\012" instead.) 

Connecting to the server Ls only the first part of the process: 
once you have the conneaion, you have to use the server's 
language. Each server on the network has its own little 
command language tliat it expects as input. The string that we 
send to the server starting with “GET” Is in HTTP syntax. In this 
case, we simply request each specified document. Yes, we really 
are making a new connection for each document, even though 
it's the same host. That’s tlie way you always used to have to 
spe^ak HTTP. Recent versions of web browsers may request that 
the remote server leave the connection open a little while, but 
the server doesn’t have to honor such a request. 

Here’s an example of running that program, which I’ll 
call webget: 

% webget WWW.perl.c&m /guanaco.htral 
HTTP/1.1 404 File Not Foutid 
Date: Thu, 08 May 1997 18:02:32 GMT 
Server: Apache/1.2b6 
Connection: close 
Contenr-type: text/html 

<HEAD><TITLE>404 File Not Found C/TmB></HEAD> 

<B0DY><Hl>File Not Found</Hl> 

The requested URL /guanaco.htral was not found on this 
server.<P> 

</B0DY> 


Ok, SO rhafs not very interesting, l>ecause it didn’t find that 
particular d<x:umen[. But a long response wouldn’t have fit on 
this page. 

For a more fully-featured version of this program, you 
should look to the iwp-request program included with the LWP 
modules from CPAN. 

Interactive Client with lOi^Socket 

Well, tliat’s all fine if you want to send one command 
and get one answer, but what about setting up something 


fully interactive, somewhat like the way telnet works? That 
way you can type a line, get the answer, type a line, get the 
answer, etc. 

This client is more complicated than the two we've done so 
far, but if you’re on a system that supports the powerful fork call, 
the solution isn’t that rough. Once you’ve made the connection 
to whatever service you’d like to chat with, call fork to clone 
your process. Each of these two identical process has a very 
simple job to do: the parent copies everything from the socket 
to standard output, while the child simultaneously copies 
everytliing from standard input to the socket. To accomplish the 
same thing using just one process would be much harder, 
because it’s easier to code two processes to do one thing than it 
fs TO code one process to do two things. (This keep-il-simple 
principle a cornerstones of the Unix philosophy, and good 
software engineering as well, which is probably why it's spread 
to other systems.) 

Here’s the code: 


#f/usr/bin/pcrl -w 
use strict; 
use 10::Socket: 

ny (Shost. $port. Skidpid. Shandle. $liae): 

unless (iARGV == 2) \ die "usage: $0 host port" ! 

I Shost . Sport) - #ASGV: 

* create a teg conncaion to Ihc spccifieU host and port 
ShandlG - 10:;Socket::INET-> ogwEP roto -> "tcp"* 

Poor Ad dr *"> sWat* 

PeerPort => Sport) 

or die "can't connect to port Sport on Shoat; $!": 
Shandle ->atitof lushE 1): # so output g^ts dierc right away 

print STDERR "[Connected to Shost;Sport] \ii*; 

* split the program into rwo processes, identical twins 

die "can't fork: $1" unless defined (Skidpid * forkO); 

* the Ifl) bloci runs only in the parcnt process 
if (Skidpid) I 

# copy the socket to standard output 

vhile (doflned (Sline = <$bandle>)) t 
print STDOUT $line: 

I 

kill { "TERM" , Skidpid); * send SIGTERM to child 

) 

* the elsell block runs only in the child process 
else f 

* copy standard input to the socket 

while (defined ($lina = <STDIN>)) ( 
print Shendle Sline: 

I 


The kill function in tlie parent's if block is there to send a 
signal to our child process (ajrrem running in the else block) as 
soon as the remote server has closed its end of the connection. 

If the remote server sends data a byte at time, and you need 
tiiat data immediately without waiting for a newline (which 
might not happen), ytm may wish to replace the while loop in 
the parent with the following: 


my $hyte: 

while tsysr€ad($handle, Sbyte. U = 1) I 
print STDOUT $byte: 

) 
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Making a system call for each byte you want to read is not 
very efficient (to put it mildly) but is the simplest to explain and 
works reasonably well. 

TCP SEB\ms WITH lO::SOCKET 
As always, setting up a server is little bit more involved than 
running a client. The model is that the server creates a special 
kind of socket that does nothing but listen on a particular port 
for incoming connections. It does this by calling the 
IO::Socket:;INKT->newO method with slightly different 
arguments than the client did. 

• Proto - This is which protocol to use. Like our clients, we^H 
still specify ”tcp" here. 

• LocalPoit - We specify a local port in the LocalPon 
aigument, which we didn't do for the client. Tliis is service 
name or port number for which you want to be the server. 
(Under Unix, ports under 1024 are restricted to the 
superuser.) In our sample, well use port 9000, but you can 
use any port that's not currently in use on your system. If you 
try to ase one already in used, you'll get an "Address already 
in use'' message. Under Unix, the netstat -a command will 
show which services current have servers, 

• Listen - The Listen parameter is set to the maximum number 
of pending conneaions we can accept until we turn away 
incoming clients. Think of it as a call-waiting queue for your 
telephone. The low-level Socket module has a special 
symbcil for the system maximum, which is SOMAXCONN. 

• Reuse - ITie Reuse parameter is needed so that we restart 
our server manually without waiting a few minutes to allow 
system buffers to clear out. 

Once the generic server socket has been created using the 
parameters lusted above, the server then waits for a new client to 
connea to it. Ihe server Ijlocks in the accept method, which 


eventualiy accepts a bidirectional connection from the remote 
client (Make sure to autoftush this handle to circumvent bufferirtg.) 

To add to user-friendliness, our server prompts the user for 
commands. Most servers don't do this. Because of the prompt 
without a newline, you'U have to use the sysread variant of the 
interactive client above. 

This server accepts one of five different commands, sending 
output back to the client. Note that unlike most network servers, 
this one only handles one incoming client at a time. 

Here's the code. 


<^!Ai5r/bin/pcfi 'W 
use 10;rSocket; 

use Net: :hostGBt; for OO va^on of gethostbyaddr 

5 PORT * 9000; # pick something not in use 

^server = 10::Socket;:lNET->new( Proto 'tep', 

LocalPort “> $P0RT, 

Listen*) SOMAXCOmi, 

Reuse *> 1); 

ijie ’‘can't setup server" unless ^server; 
print "[Server $0 accepting clients)\n": 

while (Scllent “ $server‘>accept()) ( 

$clientOautoflushCl); 

print $client "Welcome to $Qi type help f or canmand 
list.\n": 

$hofitlnfo * gethostbyaddr($clientOpeeraddr); 
printf "[Connect from Xs]\n", §hostinfo->nanie |{ 

$ellent->peerho3t: 

print Sclient ^Goninand? 
while { <$client>) ! 

next unless /\£/; #l>lanklinc 
if[/quit|exit/i)I last; 1 

elsif {/date|tinie/i) f printf $client "ItfiVn". scalar 
localtime; I 

elsif (/who/1 ) I print Sclient ‘who 2>fi,r: I 
elsif (/cookle/1 ) [ print Sclient 

'/usr/games/fortune 2>&r; j 

elsif [/motd/i )f print Sclient 'cat /etc/motd 

2>&r; I 

else t 

print Sclient ■'ComiDands: quit date who cookie 

motd\n": 

1 
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J continue ( 

print $client "Conimand? 

] 

close $client: 

) . 


UDP: Message Passing 

Another kind of client-server setup is one that uses not 
connections, but messages. UDP communicaEions involve 
much lower overhead but also provide less reliability, as 
there are no promises that messages will arrive at all, let 
alone in order and unmangled. Sttll, UDP offers some 
advantages over TCP, including being able to '"broadcast" or 
“multicast” to a whole bunch of destination hosts at once 
(usually on your local subnei). If you find yourself overly 
concerned about reliability and start building checks into 
your message system, then you probably should use just TCP 
to start with. 

Note that UDP datagrams are not a bytestream and should 
not be treated as such. This makes using I/O mechanisms with 
internal buffering like stdio (i.e. printO and friends) especially 
cumberst>me. Use syswriieO, or better sendO, like in the 
example below. 

Here's a UDP program similar to the sample Internet TCP 
client given earlier However, instead of checking one host at a 
time, the UDP version will check many of them asynchronously 
by simulating a multicast and then using selectO to do a timed- 
out wait for I/O. To do something similar with TCP, you'd liave 
to use a different socket handle for each host. 

•!/usr/bin/perl w 
use strict; 
use Socket: 
use Sye:iHostname: 

ray { $count* Shisiaddr, Shispaddr* Shistime. 

$host. $iaddr* $paddr, $port, $proto* 

$riii* $cout, Sttime, $SE€S_of_70_YEAl!:S): 

$SECS_of^70^yEARS = 2208983800; 

$iaddr gethostbynaraethoEtnaiiieO ): 

$proto “ getprotobynamet'udp'}: 

Sport - getservbyname(’tirae', * udp * 1; 

Spaddr “ sockaddr_in(0i Siaddr); # 0 mcam ki kcrnd pick 

socket(SOCm, PF_rNET, SOCK^DCRAH, Sproto) 11 die "socket: 
SI-: 

bind(SOCKET, Spaddr) |{ die "bind: $!": 

5i “ 1; 

printf "X-Hs XSs Xs\n*. 'localhoEt*. 0. scalar localtime time; 

$count " 0; 

for $host (§ARCV) ( 

Scount'H -1 

Sbisiaddr ■ inet„aton(Shost)|| die "unknown host": 
Shispaddr - sockaddr_in(Sport, Sbisieddr): 
defined (send (SOCKET, 0, 0, $hi£ipaddr]) I I die "send 
$hoat: $ I"; 

I 

$rin = 

vec($rin, fileno(SOCKET), 1) - 1: 

# ijmeont after lO.O seconds 

while (Scount (if> select(Srout “ Srin, undef, undef* 10.0)) ( 
$rtiiBe * 

($hispaddc ^ recv(S0CKET* $rtirae* 4, 0)1|| die "recv: $1": 
(Sport, $hisiaddr) " sockaddr_iD($hiBpaddr); 


ShoBt = gethoetbyaddr(Shiaiaddr, AF_IHET): 

Shlstlrae = unpackp'N", Srtirae) - SSECS_of_70_YEARS ; 
printf "%-12s ", Shost: 

printf "%3d TtsVn"* Shistlrae - time, scalar 
localtime($hiBtiiiie); 

$count--: 

1 


Note that this example does not include any retries and may 
consequently fail to contact a reachable host. The most 
prominent reason for this is congestion of the queues on the 
sending host if the number of list of hosts to ccmtact is 
sufficiendy large* 

SysVIPC 

While System V IPC isn't so widely used as sockets, it 
still has some interesting uses. You can’t, however, 
effectively use SysV IPC or Berkeley mmapO to have shared 
memory so as to share a variable amongst several processes, 
lliat's because Perl would reallocate your string when you 
weren't wanting it to. 

Here’s a small example showing shared memory usage. 

use IPC::SysV qw(IPC_PRIVATE IPC_RMTD S^IRWXH); 

$elze - 2000: 

$ld - shragetdPC^PRlVATE, S^IRWXtJj |1 die -$l": 

print “shra key $id\n": 

$i!iessage “ "Message #1"; 
shrawrite($id, $message, 0, 60} {| die 
print "wrote; ‘$raes!jage'\n"' 
ahniread($id, $buff, 0, 60) jj die "$1": 
print "read : ‘$buff'\n": 

* the buffer of shmirad is zero-charaacf cmipadded. 
subatr($buff. indejt(Sbuff. "\0")) * 
print ”un" unless $buff eq ^message; 
print "swell\n"; 

print "deleting shm ddVn"; 
shraetKSid, IPC^RKID, 0) [| die "$r": 


Here's an example of a semaphore: 

use IPC;:SysV qw(IPC_CREAT): 

SIPC^KEY = 1234; 

$id - Beraget($IPC_KEY, 10, 0666 I 1PC_CREAT ) |I die 
print "shra key Sid\n*: 

Put this code in a separate file to be run in more than one 
process. Call the file take: 

* crtaic i semaphore 
$IPC^KE¥ = 1234 : 

Sid - seiitgat($IPC_KEY* 0,0): 
die If I defined(Sid): 

Sseronura " 0: 

Ssenfisg “ 0; 

# "take" semaphore 

» wait Iw semaphore to be zero 
Ssntaop ^ 0; 

Sopstrlngl ^ pack["B!slst", Ssemnunj, Saeraop, Saemflag): 

• Increment the semaphore count 
SseiDop = 1: 
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$opstring2 “ pack("4j|&Js f" . SsenmiiM, $sefliop, $eetaflag): 
iopstriBg = Sgpsttiti&l . SopstringZ; 

seniop($id*$op£trlnR) || die **$!": 

Put this ffxle in a scpumtu file to !>e run in more than one 
process. Call tills file give: 

s'givc' tlie 

^ nm ilii^ in ihc uriginiil prucass ;ttwl yuu will see 

# rhat ihe secemd pnicess euntinm^s 

$lPejCE¥ - 1214: 

Sid = seinget($IPC^KRY, 0, 0)j 
die if 1 defined(Sid): 

$^I^^^lnuIn ^ 0; 

S.qeinflag “ 0^ 

# Dt'cremcnt die scmaptiofic count 
Ssemop = l ; 

$op£triiig - pnck(*s!sin l Ssemop, Ssenflag): 

seiiiop(Sid,Sgpstring) || die '‘$1'*: 

The SysV IPC exxie abt)ve was written long ago, and il*s 
definitely clunky kx)king. For a nK>tc iiKKlem look, see the lPC::SysV 
nxKiule whicii is included with Peri starting ftom Peri 5.005. 

A small example demonstrating SysV message {queues: 

use iPC;:Syi3V qw(IPC^PRTVATE IPC.RMID IPC^CREAT S_IRWXU) i 

my $id " msgget(1FC_PR1VATE, TFC^CRRAT | S^TRWXU): 

my $sent - ’'meaaage'*: 
my $typG * 1234; 


my Srevd; 
my $type_rcvd; 

If (defined $id) I 

if CESgsnd($id* psck("ll a*", $typersont. $£ent), Ol) f 
if (aggrcv($id, $rcvd* 60» 0* 0)) t 

C$type,rcvd, Srevd) “ impack("il a***, $rcvd); 
if ($rcvd eq Ssent) t 
print 'okayVa"; 

} else [ 

print '^not okay\n"; 

I 

t else I 

die ”if tosgrev faiIed\Ti‘': 

I 

I else I 

die '*# msgsnd fflilRd\n^; 

I 

rasgctl($id. IPC_^RM1D. 0) || die msgctl failedr SUn^; 
die msgget falled\Ti"; 

1 


Most of these routines cjuictly l)ut |x>litely return undef 
when they fail instead of causing your program to die right then 
and tlicre due to an uncaughi exception, (Actually, some of the 
new Socket conversitm funclton.s cniakO on bad arguments.) It 
is iherefore essentiaJ to check return values From these functions. 
Always Ix^gin your socket programs this way for optimal 
success, and don't foiger to add -T taint checking flag to the #1 
line for ,servers: 


«»!Awr/bin/pcii -Tw 
use strict; 
ase sigtrgp: 
use Socket: 
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SECTIOM 7 


By Rich Morin 

The Process Tree 


Which processes do what 


'rhe initial design of Unix (by Ken Thompson, Dennis 
Ritchie, et al) was based on the idea tliiil large jobs could be 
done by lots t>f little programs, working together. Ran of tiie 
reason for tins was that the avjiilable hardware had only 
minuscule amounts of RAM. Another pan was the designers' 
dislike of large, monolithic programs. 

Mac OS X inheriLs this modular approach. Most of its 
programs aren't ''little", especially by the standards of traiiy Unix, 
but there are cenainly lots of diem. On my fres lily-booted 
desktop machine, 1 found 62: 

% ps -ax I wc 1 

Tlie conintand-line options (-ax) tell ps to show all 
processes, even if they iK^long to another user or have no 
controlling terminal. Using another of ps s many options, we cm 
take a detailed look, concentrating on the commands and their 
parentage. Stretch a Tenninal window really wide, then try: 

% pa axu pld.ppid. .ccuranand 


PID 

PPID 

rr 

USER 

CQHHAND 

1 

0 

?? 

root 

/Bbin/init 

2 

1 

17 

root 

/sblri/Diarh_1 ait 

51 

1 

17 

root 

kextd 

71 


1 7? root update 

519 

536 

ard 

root 

login 'pf tdm 

540 

539 

Hid 

rdm 

-tesh (tesh) 

1506 

540 

Htd 

root 

ps -axo pid ppld tt user rooiniFind 

674 

536 

p2 

root 

login ’pf rdm 

675 

674 

p2 

rdm 

-tesh £tcah) 


Tlie PID (PrcKXiss ID) and PPID (Paanit Prtx-ess ID) colujmis 
allow us Uy gitess at the ''genealogy" of each prtK'ess, If a prcxess has 
PPID 1, k>r iastance, its "ixirenf has PID I Note, hfiwever, that a PPID 
of 1 may also mean that the original parent pnxess has terminaitxl 
The IT (“lerminaP; originally from teletype) column tells us 
the identity of the controlling terminal ('‘??' for none), Hecause 
most OSX applications have no contr<»lling terminal, this field is 
insufficient to distingui.sh apps from backgrouni:! processe,s. 

fortunately, the USER (username) and COMMAND columns 
help to clear this up. Apps generally run with the username of 


the logged-in useq in addition, most app,s have long path names 
which include directories such as "Applications . Also, the names 
of BSD-derived daemons often end in “d" (e.g,, conligd, oipsd) 

If you’re seriously interested in Itxiking at processes (e.g., to 
figure out wliich one is Ixjgging dowm yimr system you 
should also investigate ps1at(1), top(1), vm stat(1). Apple’s Pnx'ess 
Viewer utility Ls als(.> handy, but note that it may not report 
information in a manner that is consistent with the command-line 
ux>ls. For example, it shows a prxKcss named "Window 
Manager", which ps<1) and top(1) do not list... 

BACKGKOUND PRIXXSSES 

When OSX stiris up^ it initkites a manlier of backgrtiund 
processes (commonly referrctl to as “daemons", after the "anendam 
spirits" found in Greek mythology). Ret'ause these daemons liave 
low Process IDs, they appear at the start of ilie listing. 

Note; Although OSX uses a 32-bit value (piolj) for priicess 
IDs, it "wraps" the IDs at “32K, so a ps(1) listing taken from a 
long-running (and/or busy) system may show other processes 
with low' IDs. Interestingly, FreeBSD does not seem to limit IDs 
in diis manner. 

Most daemons are started up by init(8), as part of the system 
start-up pRK'ess. ^fliis accounts ft>r the long list of pnx.csses 
whose PPID is L Sc^attered in this list, however, you may see a 
few prtKesses witli PPIDs of 2, indicating that (hey are children 
of mach_init(8). Finally, some applicaiions (c.g,, iChat) and 
daemons (c.g., loginwindow, WindowServerJ start up their own 
daemons. 

Here’s an annotated list of st)me liackgrotmd pnx:esses that 
show' up <jn my machine. Licking any ntlier organizing rationale, 
ri! use alphabetical order. If mailing else, that will make the list 
easy to navigate (:-): 

AppleFNeServer - fxrrsonal tile sharing server; supports 
Appletalk Filing Protocol (AF'P) over Iniemct Protocol (IP). 

ATSServer - Apple Type Stilution server; enables system- 
wide font management. 

autodiskmount(8) - checks and mounts disk-lxised file systems. 


Rich Morin hiis been using computers since 1970, Unix since 19B3, and Mac-based Unix since 19H6 (when he helped Apple create A/UX 1.0). When 
he Lsn't writing this column, Rich runs Prime Time Freewaa- (www.ptf.COm), a publisher of books and CD-ROMs for the Free and Open Source software 
community. Feel free to wrile to Rich at rdm@ptf.COm. 
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automount - autoniatically mounts and unmounts network 
(Nf*'S and AFP) file systems. See amd(8) for information on the 
Iraditional (NFS-only) variant of tills daeinon, 

configd - maintains dynamic configuration information 
ahKJUT the computer and its environmeni {e.g, network). 

coreservicesd - core services daemon. 

crash repo rterd — logs inibrinaiion about prognmi crashes. 

cron(8) - executes scheduled commands. See also crontab(14)- 

cupsd(8} - Common Unix Printing System daemon. Hun 
“apropos cups" to sSee an extensive list of man pages. 

DirectoryService - directory’ server for Apple’s Open 
Direaory architecoire, 

dynamic„pager — assists the kernel with managing swap 
files for virtual memory. 

httpd(8) - Apacfic hypertext traasfer protocol server; may be 
replicated, for performance. Run "apropos http” to see an 
extensive list of man pages, 

inetd(8)- internet “super-server”; listens for connections on 
certain internet sockets. When a connection is found on one of 
its s(x:keT.s, it decides what .sei^ic:e tiie socket corresi^onds to, 
and invokes a program to service the request. 

keKtd(8) - handles reciuesLs from the kernel to load kernel 
extCTLsions (kexts). 

loginwindow - handles miscellaneous prtxress- and session- 
monitoring functions (c.g., login, logout, restart, shutdown, and 
restarting of the Dock and Finder), 

lookupd(8) - c’aclies directory service infonmitioii (e.g., user 
accounts, groups, printers, e-mail aliases and distribution lists, 
computer names, Internet addresses). 

mDNSResponder — multicast-DNS responder; advertises 
network services (sucli as AFP tile sharing) provided by this 
computer (part of Rendezvous). 

netinfod(8) - serves Netinfo infbnmtion to the network. 
Run "apropos netinfo" to see an extensive list man pages. 

nfsiod(d) - typically, several copies of this daemon will be 
running on any NFS client machine, servicing asynciironous I/O 
requesLs. HxIs daemon improves NFS performance, but it is not 
required for correa operation. Run ’apropos nfs” to see an 
extensive list of man pages (but ignore the b<jgus hits for 
conflg(5) and confstr(3) :-), 
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ntpd(8:Free6SD) - Network Time Protocol (NT?) daemon; 
sets and maintains the system time of day in synchronism with 
fntemel standard iime servers, 

pbs - pasteboard server (similar to the Cliplx>aid in Mac OS 
9); enables the exc hange of data between applications. It is also 
tlie data-transfer mechanism used in dragging O[)erations. 
(started by loginwlndow), 


update(8)- helps prcXecl the integrity of disk volumes by flushing 
volatile extehed file system data to disk at thirty second intervals, 

WindowServer - responsible for I'udimentaiy screen 
displays, window compositing and management, event routing, 
and cursor management, it coordinates low-level windowing 
lx:havior and enforces a funclamental uniformity in what appears 
on tlie scTeen. 


Security Server - oversees system authori7.alion, 
authentication, and keychain access, 

sipd — Seivace Location Protocol (SLP) responder; 
advertises network services (such as AFP file sharing) provided 
by this computer, 

sshd(8)- with ssh(1), replaces rlogin(l) and rsh{1), providing 
.secure encrypted communications between two imtrusted hosts 
over an insecure network, Pun “apropos ssh” to see an extensive 
list of man pages. 

syslogd(8) — reads and logs messages to tlie system console, 
log files, other machines, and/or users as specified by 
syslog.cont(5), its configuration file. See also svslog(3). 

SystemUIServer - displays itetns on the righi-hand end of 
the menu bar; loads menu and dock extms as plug-ins (started 
by WindowServer). 
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ir^rERAcnvE prwesses 

Most apps arc children of the WindowServer daemon. Their 
names should be quite familiar: Dock, Finder, fChat, Preview, 
Terminal. As noted alx>ve, some apps start Lip their own 
daemons. For exain[)lc, iChat starts up iChatAgent (probably to 
handle communications). 

Tlie lineage for command-line progiums is a bit more 
complex. Assuming that yoifre using Terminal, it slumld kx>k 
something like this: 


PID 

PPI13 

TT 

USER 

COMMAND 

17S 

I 

?? 

rdm 

.../WindowServer ... 

516 

173 

?7 

rdm 

.../Terminal ... 

539 

536 

p\ 

root 

login pf rdm 

540 

539 

pi 

rdm 

tesh (tesh.) 

873 

540 

pi 

root 

top 


As tliese lines show, init(8) started up WindowServer, which 
started up ilie Terminal. Tlien, to generate an interactive shell 
window, Terminal started up login, which started up tcsh(1). 
Finally, t ran top(1) from the command line. 

Careful Reader will notice that the u.sername for login and 
top is root, rather than rdm. Because these prtKiesses need to do 
some things which a normal user is not alkwed lo do, they have 
been created as se!uid(2) executables: 

l Is -1 /usr/bin/{login,top) 

-r-sr-xr-x 1 root wheel /usr/bin/login 
1 root wheel .,/usr/bin/top 


Fukther READmO 

In a tradiritsnal BSD system, the first place to look for 
infoiiiialitxT t^n cx>mjiiands and diemons would lx: the manual. 
UntbrlLinately, many OSX commands and daemons do not have 
ac:companying manual pages. Kven when man pages are present, 
they may nai Ix" u[Ho-date, let alone cusiomi^^etl to reflect changes 
which Apple has made, other docunientation it has developed, etc. 

A comprehensive attack on thi.s problem has been 
suggested by parties inside and outside of Apple, l>ut (AFATK) no 
significani effort has ixen made as yet. If you w^ould like better 
manual pages, let ADC (etc.) know! 

In the meanwhile, here are some places where I found 
useful inforniation for tliis seaion: 

http://vww.westwind.com/reference/OS-)(/bacl<ground-processes.html 

http://developer.apple.com/techpubs/macosx/Essentials/ 

SystemOverview/BootingLogin/chapter_4_section_5.html 
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JOHN AND PALS' 
PUZZLE PAGE 


By John A. Vink 

Puzzle 2:What's on the menu? 


Try io w>lve this pmgnimming puzzle before the score drops 
to zero. Tile puzzle is presented as a rli.seiission among 
engineers in a chat room. As tiie engineers gatlier inronnalion 
and make suggestions, see if you can find the solution. If you 
solve the prolilem liefore you gel to die end of the puzzle, you 
gel the score in the left hand colunin* 

SDK: I kjve tiie monotony of a steady paycheck. 

Argus: Tell me nboui it, SDK, 

100 ChrisE: OK, under wiiai drcuiiistances does CfetNewMBar 
return nil? 

95 BMA; No MBAK resource? 

ChrLsE: Tt*s there. 

90 SDK: Out of memory? Like, railly out? 

ChrLsE: Mac OS X 

SDK: Hell, mine runs out of memory all the time, 

SDK: 1 can tell l^cause it gels slower and umsole gels really 
talkative. 

05 BMA: What's ResKrror and MemError have U> say uiK)ui it? 

80 ChrisE: ResErrorO is 0; MemErroK ) is 0. 

BMA: Your computrons are leaking out of the lx:)ttoiii of t!ie 
case, you ni^ed In plug it up with silicone fittings. 

BMA; Is this *l\ittle'S machine? It's cursed, 1 tells you! 

75 Argus: Resource not linked in? 


70 Argus: Can you use GetRcsourte on the MBAR? 

ChrLsE: Whaddya mean "not linked in"? 

Argus: What are you really trying to do? Is the resource really 
available to your app? 

BMA: When you said "it's there", did you look in the executable 
or in the project to verify? 

65 ChrisE; OK, 1 liave one project, two largeis. The targets build 
slightly different ways, hut with identical source, resources, etc. 

ClirisE; One target builds and runs line. 

60 ChrisE: Tiie other (mostly identical) target gets nil from 
GetNewMBan 

BMA: Y(Hi got Re.sorcerer liandy? 

55 KeithS: Maylie one target re<|uircs a MDEF that isn't present 
in the other? 

Pie R, Square: Why Ls ResEmirt ) 0? 

50 ChrisE: 1 DeRez the .fsrc files in hotli packages and they're 
identical. 

BMA: Bit for bit?! 

45 Argus: 'fhrow in a GetResoiirceCMBAR', x) and sec if you gel 
a resource fiack. 

Pie R* Sqiiarer 't hey link to the same set of liliraries? 

ClirisE: OK, what's liex for MBAR? I'm in gdb. 

JAV; BaseMaster says: 4D424152 


John A, Vink (aka "JAV”) is a software engineer for Apple Computer, Inc. He lakes a break in the summer to Follow INKS on tour. His pais arc a 
bunch of sman friends scattered tliroughout the Mac programming iandscaj>e. You cm contact liim at viak@apple.eom. (Tiie pals reference makes 
sense with ilie "John And Pals' Puzzle Page" title) 
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BMA: For tile retord, print/x ’’MBAR'' in gclb does what you 
waul. 

40 BMA; Do you load any oilier resources Ix^fore loading the 
MBAR? 

ChrisE: Nope. 

35 KeithS: gdh ; hr GetMenuBarO; call (int) Getltoource t 
'MBAK', 128 ) and see if it works. 

ChrisE: Get Resource returns 0. 

Pie R. Scjyarc; And ResEirO is 0? 

ChrisE: ResKrror is 0. 

30 Argus: ResError is volatile and can get reset tjuickly, 

25 BMA: Your plist is hosed and your resource file is not being 
opened at all. 

BMA: Diff the plists. 

20 KeitliS: call tvoid) IYiniResour<x.^Chain{l ) 

BMA: Do itie resource files inatch die app names? 

15 ChrisE: PlisLs differ only in the name of the app, hut in the 
one that's hrtjkcn. die plLst name differs from the name of its 
app, 

BMAi Tfiere you go. 


ChrisE; In the one that works they match. 

ChrisE; Bravo, guys. JAV, write this up. 

ChrisE: PrintResourceChain shows my .rsre isn't there, probably 
liecause the plist has the wrong name. 

10 KeithS; S<i CFBuiidle is failing to open your resource Ole 
because it's got your exectuaiile wrong. 

BMA: Well, in your case the Ole itself has the wrong name, but 
yes. 

5 ChrisE: The Ole has die same name as the executable, but the 
plist entry is different. 1 had changcxl the name in die target 
editor but an old name persisted in tlie plist. 

BMA: Oil I see, 1 got it backwards. 

ChrisE: Executes correctly now. 

ChrisE; Thanks! Score: 

85-100 That was pretty good. 65-80 You must have called a 
friend on the inside. 45-60 You've lx;cn carl ionizing your apps 
like a gotxl developer. 25-40 You see, GctMenyResource is a 
classic Mac OS APl. 

Score: 

85-100 Tliat was pretty gCK>cl 

65-80 You must have called a friend on the inside. 

45-60 YoiiVe been i:arlx)nizing your apps like a 
g(XKl developer 

2540 You see, GetMenuRestiurce is a classic Mac OS API. 
0-20 Slick to C<K*oa and command line apps, 



August 2003 • MacTeoi 


Puzzle 2: WuaTs on the menu? 


39 


















VIEWPOINT 


By John C. Daub 


Apple’s DeveloperToolchain 


Or, bow I teamed lo appreciate Objective C 


Mac OS X l>een publicly available for over two years. 
Many others and myself have come to appreciate the "native’' 
offerings that Mac OS X brings, such as inaeased sUiirility and 
true [fiulituusking. But one thing that still boggles my mind is 
how many Mac OS software devek>ptTs still balk at the "native” 
Mac OS X software developer toolchain; l>y tliat 1 me;in: CtKtra, 
IVtjjea Bulkier, Interface Builder, and Obiective C, I have found 
tJtis tcK>lchain grc^itly increases my pn)duriivity over my previous 
t(K)lc!iain, and it pains me whenever I Find a Mac OS software 
developer that simply refuses to give it a try. I adniit I too had 
"bracket shock'' wlien I first looked at Objective C source code, 
but Tm glad I didn't let tliat scare me away because IVe found 
a way to develop software faster and better than the way I was 
previously developing. 

Cocoa 

Cocoa is the name for Apple\s native object oriented 
application development frameworks. Ihese days it's safe to say 
Cocoa's chief competitor is PowerPlant, Meirowerks' ofrjen 
oriented application development framework. Cocoa and 
PowerPlant work to accomplish the s;uTte goal: wrap up the 
prcx'edures of the operating system and present them to the 
developer in an object oriented manner, along w'ith utility and 
helper classes that solve corninon programming problems to 
facilitate faster application development. I believe Crx’oa does ir 
lx‘Uer, and I think that's due in part to the maturiiy of Cocoa as 
an API, I’ve found Cocoa's ai>iliiies to be very broad and very 
deep, providing me with just about cverv'iJiing \ need apart from 
whatever specifics there are to iiiy application's logic. As an 
example, I w'anted to hack up a small application to help me 
keep my notes, I started in PowerPlant and after two weeks was 
greaily fnisirated at how much work i had done and how liitle I 
had accomplished Ijec^aose in that time i w^as still struggling to 
get the foundation for die application established, I had just 
finished going through the learning Cocoa lxK)k and decided to 
try using Ccxoa to liack up my appliaition. Even with my 
inexperience, witliin a day I iiad gotten further working in Cocoa 


tlian I did in PowerPlant, and I liclieve this was due to the 
breadth and depth of the API that Cocoa provides. 

One thing about Pow^rPlant’s design is the "buffet style” 
approach it takes, PowerPlant i.s intentionally designed so that its 
classes c.*an be used together or separately; one is ahle to pick out 
and use what looks kiterestlng. While I certainly find merit to tliis 
approach, in my years of using PowerPlant I’ve also found myself 
CKTcasionally fnistrated l7y this a[)proac'h. When I w^orked for 
Perv'asive Softw^are developing 'I'ango 2000 [ used tire MacApp 
framework, which is more of an “all or nothing” ftaniework as it 
has a common base class wliicli most all classes inherit from: 
TObject, Cocoa has a similar afiproach witli mtist all classes 
inheriting from NSObject. I actually didn’t find this approach as 
bad as I was lead to believe, and since my MacApp experiences 
fVe grown to actually appreciate and prefer a common "object" 
ba,se class. This Is because I’ve found myself striving to write 
code in more of a true oltjeci oriented manner, and it helps when 
everything you’re working with is m object. 

When I work in Coexta I feel like rm i^rogramming the 
system in an oi^jeet orientetJ fashion, unlike Cartxrn, which is 
procedural in naUire. One tiring that helps make tills possible is 
how' the Objective C language and runtime is Integrated into the 
system. I'll speak more on Objective C later in ihe anicle. But 
along the lines of integration is the core development 
applications: Interface Builder and Project Builder. 

PRt)Jli(:T Biulder 

Projeti Builder is Apple's project Tnanageinent tool. IPs akin 
to the Code Warrior IDF in terms of the problem it’s providing a 
solution for-project management. Most Mac programmers these 
days li;ive used CcxteWarrior and feel that Project Builder i,sn't 
quite the tool that the Code Warrior IDH is, I tend to agree with 
titai asse.ssment. There arc a lot of nice things that Project Builder 
can do liecause of how it's implemented, such as how It takes 
advantage of the runtime environmeni that Mac OS X provides 
whereas the CtxleWairitir IDH is still WaitNextEvenL'Thre 2 id 
Manager based, 1 do find CodeWLirrior’s class browser features to 
ix^ wonderful and miss them greatly when 1 work in Projeci 
Builder, liut at least as of CtxleWarrior Pro 8.3 its class browser 


Jofm C. Daub Is a MacTeeb Magazine Qintriiiuting Editor, u Mac OS Software Developer for Aladdin Systems, Inc., and Grand iXxth-bah of Hsoi’s 
Shop. John resides in Austin, Texas USA witii his wife, three children, two cats, and a rank full of tropical fLsh. He strongly Iielieves CaUfomian’s have 
no idea wlial good BBQ is. llianx to Adriaan Tijsseling for the aitiele review. You am reach John via email at hsoi@hsoi.com. 
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didn't support Objectivo C (hcck, die functio[i popup still 
doesn't grok Olijcclivc C). But then I find Project Builder’s 
integration witli API documentation very handy. 1 find myself 
preferring Metrowerks' compilers to gcc and tliat tlie MSL C++ 
libraries are an excellent piece of work. But dten tool integration 
like die Code Warrior IDE and Constructor just isn’i ifiere like it 
is with Project Builder and Interface Builder 

Project Builtler is certainly a more than usable product, btit 
it tloes have a ways to go, especially if' i! wants to bring the die¬ 
hard Code Warriors into the fold. As I revise my writing of iliis 
article, WWDC 2003 just ended and at the show Apple 
annciuneed Xcocle, dieir new integrated developmeni 
cnviromiient (see Dave Mark’s guided tour of Xcode elsewhere 
in this issue). 1 iielieve Project Btiilder is presently the weakest 
link in die Apple tookliain, but the features and promises that 
Xcode makes certainly raise the bar for Mac: developer Uxils. 
Let’s hope Xcode can tie liver on iluxse promises and that the 
competition lieiween Ayiple and Metrowerks leads only to g(K)d 
things for Mac develoyxfrs and ultimately Mac iLsers. However, at 
present %ve still have to work with Fniject Builder and it remains 
the weakest link in die chairn but it doesn't bother me that much 
Ixrcause I find Interface Builder to lx: one of the sirfingcr links 
in the chain. 


Lytertacii Buildek 

In my experience^ I have fountl Interlace Builder to be a 
hands-down better tcKil than Cemstnittor. Constructor is a good 
and necessary Lotil, indispensable for PowerPJaot programming. 
But I have found Interface Builder Ixtiter suits my needs. 

1 find the w^hole GUI layout process works nicer in Interface 
Builder. When laying tiut widgets, there are guides to help 
enftirce the layout dimensions and measure me nts from the 
Apple 1 luman Interface Guidelines - Fm not wasting time and 
straining my eyes to count [>L\eb, 1 also love how^ 1 can ivy out 
tny Gin from within Interface Biiikler to really gel a good idea 
about liow' my GUI is going to ItKik and feel. It’s a terrific t(x>i 
for RAD <levelopmcnt and prototyping, not to mendon moc'king 
up scTCcashots for de.sign documentation. 

Even though the application is allied Interlace Builder, I 
coasider it a Uxil for more llian just building your GUI - ifs a tool 
to i>ui!d your drjea.s and establish relationships Ixiw^cen diose 
objects. In Interface Builder you can not only construct your GUI 
objects, but you typically will create other ol-jjects sudi as 
cxinlrollers and daUi sourc'es. From within Inierfacx." Builder you 
can create the (sub)class, instantiate the object, and even generate 
the skeleton scuirce ccxJe which liUerface Builder am automatiolly 
add to yotir pn>jc-cL u|xn in Project Builder When generating 
source code, Interhice Builder can generate it as Java or Objecnive 
C. While Java's a gexxi language, when fm developing Mac OS X 
software Fin finding tliat I [prefer Objective C. 

Objective C 

The more I use Objective C the more I find it to be a 
really cool language. It looks scary at first, but it takes maybe 
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30 minutes to tmderstand the basics of Objective C and 
yxThaps a weekend of tinkering with aitorials and sample 
projects to really grok iiow the language works. If you’re 
familiar with object oriented programming from C++ or Java, 
you'll find many similar concepts in Objective C; in fact, 
Objective C influenced Java's development. Once you 
understand how the language works, ilten yotril be ready to 
understand how Cocoa works. 

Just Ix^cause a language may not be widely popular, like 
Lttin, there's sometimes still merit to learning and knowing that 
language. Objective C ultimately is C with, in my opinion, l>eLter 
object t)ricnied concepts tacked onto it than C++ tacked on to C. 
1be [^racket syntax is Ix^tier thought of as message passing. In 
C++ you might do this: 

object->11etkod0 : 

or a PowerPlant programmer might do this: 

vidg0t->BroadcastMeEEageCinsg . loPiirain); 

In Objective C you’d do this: 

I object niethodl ; 

In terms of what it functionally means, it’s all the same: 
liaving an object do something. What's differeol is liic syntax 


Whistle Blower 

Enterprise server monitor and restart utility 
whistleblower.sentman.com 

Connect to and validate the response from web servers, 
cgi scripts and over 23 orfier types o f servers. 

Send email, pages and perform unattended restarts via 
MasterSwitch or PowerKey. 

Shifts make sure that the person on call when the server 
goes down is the one who gets Hje page. 

68k, PPC and Conbon 

Web based administration lets you check on and restart 
your servers from anywhere. 

Customize your response to an outage wfrfi Apple Script 

emoil us at whi5tlebl0wer@sentman.com 


for how messages arc passed to objects: in C++ you caU an 
object’s function, in Objective C you're passing the object a 
message. What’s also different but not apparent from looking 
at the code is in C++ the function and it arguments are joined 
together in compiled code, whereas in Objective C the 
message and the receiving object aren't bound together until 
the program is running and the message is actually sent; this 
is called dynamic binding. Dynamic binding gives 
Objective C a great deal of power as an object (oriented 
programming language since at runtime a developer can vary 
not only the messages sent but the ol>jecls receiving those 
messages. Receivers and messages can be determined on the 
fly and Ik: made contingent upon external factors like user 
input. Ultimately I think of Objective C as just another 
language in my toolset. But if you think about speaking 
languages (English, Spanish, French, etc.), the more 
languages you know the more you can understand, describe, 
and work with the world around you. Knowing more 
languages helps you think a little different, a little better ” 
your horizons arc l)roadened. 

One tiling I should tell you Ls tliat years ago I worked as an 
employee of Metrowtrks as a PowerPlant engineer. As much a.s 
I adore PowerPlant, Fve really come to tliscover the limitations 
with the C++ language. 1 believe iltat C++ is a great language for 
generic programming (templates are awesome), but I'm finding 
Objective C to he a better language for oliject oriented 
programming. Objective Cs support for dynamic typing, 
dynamic binding, and ntessaging feel to me to lend fitter to the 
paradigms of object oriented programming. And widiin Apple’s 
developer toolchain, 1 (x-Jicve Objective C Is the linchpin that 
makes it all possible. 

Sure 1 miss C++ isms like using stack-based classes for 
cleanup, but Fm alsti finding that with well-crafted code I 
don't need those facilities when I write in Objective C. I've 
found constructs like categories to be very useful so that 1 can 
extend a class without having to siibc!as.s and create a new 
type (e.g. I can add .Str255 “constructors” to NSString via a 
category). What 1 find mo.st powerful about Objective C is 
how the language is dynamic and binding occurs at runtime. 
'Phis has allowed me to write some really neat code that I just 
couidn’i do in a static compile-tinie binding language like 
C++. But I haven’t abandoned C++ entirely because again it’s 
a great generic programming language. Plus if you have to 
write code that’s crass-platform, C++ makes for a good 
choice. You can write your generic engine code in C++ and 
share that across platforms, then write your platform-specific 
GUI code m Cocoa (for Mac). The Objective C++ language 
and compiler support allows C++ and Objective C code to live 
together in almost perfect harmony. 

So WHAT? 

Sometimes it feels strange to me to use something (Cocoa) 
other than what I had a hand in creating (PowerPlant). 
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Sometimes 1 feel that having Objective C on my resume won't 
get me as far as it wQui<l having Java on my resumt\ But Fve 
gotten over tlicsc feelings, Tve come to a point in my career 
where I no longer care to be a religious zealot about a 
computing platform or a programming language or a 
development framework. 1 just want to be a zealot for creating 
insanely great software for Mac OS X. My users don’t care if 1 
use Carbon or Cocoa, PowerPlant or REAlliasic, C++ or 
Objective C, CcxJeWarrior or Apple tools. Users just want 
scjflware dial provides solutions and works well, and they want 
it today. So when 1 am presented with a programming problem, 
T don’t first pit:k my toolset Ltien cram my solution into it. 1 now 
analyze the problem and work to determine what tools will be 
most appropriate to solve the problem. Maybe Java and the 
Swing libraries will he the best solution. Mayfx^ C++ and 
PowerPlant or Qt will be a more appropriate tool. Or maybe 
quickly hacking up a Perl script will be die best tool for the job. 
The more variety of tcxils 1 have in my loolchesL, the more 
power I have to pick the right tool for the job to ensure I can 
do the job effectively. 

I have discovered that when T use Apple's developer 
toolchain of Cocoa, Project Builder, Tnlerface Builder, and 
Objective C all coupled with the killer environment that is 
Mac OS X, I find 1 can deliver more robust solutions in less 
time, ll may not always Ire my toolset of choice for a 
particular project, but at least since I know about and how 
to use the toolchain I can see the disadvantages and 
advantages that it has. For example, a project I'm presenily 
working on has requirements that forced me to drop Project 
Builder for CodeWarrior because of some issues with the 
-header-mapfile option that I couldn’t work around any 
odier way. But Tni still using Cocoa, Interface Builder, and 
Objective C (along with C, C++, and Objective C++) in this 
project. Generally speaking, Apple’s toolchain is becoming 
my toolset of choice because of the power, speed, and 
flexibility inherent in the system. Jn a few years 1 may feel 
differently, PowerPlant X is on the horizon and I know 
Mclrowerks is working hard to maintain their lead as a tools 
platform. And with the release of Apple’s Xcode, it’s obvious 
that Apple isn't re.sting on their laurels when it comes to 
developer tools. I hope tliis competition in the developer 
tools space will only lead to better solutions for developers, 
which means better software for end users, and that keeps 
us all in a job. 

If you haven't given Apple’s developer toolchain a try, 
dedicate a weekend to trying it out. Set your biases aside 
and just give it an honest try. Even if you don’t stick with it, 
at least you’ve been able to evaluate it from a more hands- 
on perspective. By knowing a little bit more about the 
toolchain, it helps you to expand your knowledge and 
toolset ! believe that will make you a better and more 
valuable software developer. 
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UNTAMCLIlUG 
THE WEB 


By Kevin Hemenway, National Resident 

Server Side Includes with Apache 


Including Content within Other Content, 
And More 

In our last column, we chatted about turning on our web 
server, geUing more information concerning how ii\s been 
installed (like where the log and configuration files are), and 
then took a quick look at editing the primary control filcj 
/etc/httpd/httpdconf. Afier w'e made our changes (intended to 
circumvent an Evil ISP’s port filter), vve learned of an 
alternate route to restarting Apache by using the command 
line utility apachectl. 

All relatively Duplo. Let’s Irreak out ihe Ijegos. 

Birr First, Consider Homeiand Security,-, 

By running a web xserver, you’re inviting anyone on the net 
to stop by your computer and access Tiles yoiTve deemed 
worthy, Ihis should be a scary thought; what about all the files 
yt)u DON’T deem worthy, like development versions of your 
software, database files lhai contain customer information, or ihe 
source code to any well scripts you may be running? Even if 
youVe got a dedicated machine solely for your web site, you’ve 
still gol to wear another hat: that of security princess (“I ieel 
preetTty, OoOh soOO PrefTtYvl”), 

Tltis isn’t securiry^ like in software downloads, where you 
concern yourself with viruses or trojans or pirated registrations. 
Witli web server secui ity, yoti ve got one wide- 0 [ien front door, 
accessible to anyone who deems to visit. Any script you run. any 
softwaie you install, any senice you turn on - all are more 
points of access for a disgruntled cracker. 

While we'll talk about securit)^ when necessaiy, there are 
two books that will put more diamonds in your tiara than 1 ever 
could. Both were sent as review copies, and IxJtli have since 
earned welcome places on my Ixiokshelf. 

The first, Mac OS X Maxitnnm Secimiy from John Hay and 
William C. Ray, covers every^ aspect of liardening your Mac OS 
X insiallarion, Broken up into rliree primary sectioas, it gels you 
into tlie mind.seL of tliinking secure, follows up with different 
ways people get into systems, and then instaicls on how' to 
actually batten down the hatches. Encompassing far more titan 


just Apache, Td recommend it to all readers, not just those 
serving weh pages. 

The second is much more specific to our topic: Maxim urn 
Apache Secunty by Anonymous. Psychotically coiiiprehensjve, it 
covers exactly (with source code) how Apache handles variaus 
bits of its own logic^ as wdl as how it interacts with third party 
software like databases, scripting languages, and modules. 
Unlike Mac OS X Maximum Security, it assumes you already 
have a strong knowledge of how Apache works. If you do, and 
you're reading my columns solely for their rliythm, thb is a liook 
you should consider adding to your collection. 

Yeah, Yeah, Yilv.ii “ Sekvtr Side Incxudes, Vam.\nos! 

Server Side Includes (SSI) are an Apache !milt-in that, at its 
simplest, allows you to include one hit of content within another, 
[f you're iliinking variable interpolation, you’ve nailed it on the 
head. For wel> page design, this l)ecames very helpful in regard.s 
to navigation Ixirs, headers, footers, copyright statements, or 
anything intended for every page. IVe designed entire sites using 
SSL with tile content files being nothing more than semanUc 
headers and panigi aphs, and the pretty' “shell'' lieing included by 
Apatlie upon rec|uest. Wheji a redesign ocairs, modify two or 
tiiree files and Pm done - the bulk f>f the site, containing 
hundreds of pages of content, remains unmodified. 

That's not all SSls can do, however. With a dash of 
conditionals and a smidgen of regular expressions, yiiuVe gol a 
feature set that can quickly jx^rfoini some interesting tricks for 
when you don) need (or w'ant) the power of FHP or Perl (which 
we’ll cover in future columns). 

Enariing Server Side lNci.irDES: The Ecology of a Moddue 

Even thougli they're built into Apac:he, SSI’s aren’t enabled 
by default. If you recall from the last column, the easiest way to 
learn about a feature in Apache is to just search for it in 
/0tG/littpd1ittpd.conf. Open said puppy up in your favorite 
authenticating text editor (BBEdit for me) and do a search for the 
word "includes". Yo\n first match should be: 

LDadXoaule Inctudcs_modulG llbexec/tiltpd/mcid_iriclijde. so 
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the lx\sE-kcpt gaming secret Gamegrene-com, articles for Apple's Internet Developer and the O'Reilly Network, etc.), he went out twice this sumnier, 
only to scurry back inside like a disgruntled cockioach. Qintict him at morbus@disobey.com. 
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Most of the features within Apache are ctjntrolled by 
modules, whicli can l>e.st f>e descriljed as a "pltigin” lo the core 
wd) server code. A decent atnount of modules ship widi Apache 
already-you'll see them alxjve and l^elow our first search result. 
Here, we Ye loading a module named incliJdes_module. which is 
located on liie hie system at Aisr/litecec/httpd/mod include.so i Ajsr 
l'>eing the Apache root directoiy' via HTTPD_ROOT, see last 
column). When a module is enabled (indicated by no preceding 
etjmmcnt characleTj #). itY ready to he eonhgurcd for use. 

For eveiy LoadMocKile, tlieie's a matching Addiyiodule shortly 
after, lb cx>iTectIy enable a mcxiiile within Apache. Ixith lines need 
to exisi uncommented. Tlie match to the alx>ve LoadModule is 
AddModulemod inciudac. wliich you’O see in another fifty lines or so. 

Any programmer can write a module to A]:)aehe, and a 
healthy list of third party enhaneements is availaldo at 
http://modules.3pact1e.org/. Most modules are named 
mod_SOMETHING, like modjnclude, mod_php, mod_access, 
etc, although there are occasional exceptions. If you Ye 
interested in exploring module creation for Apache, check out 
WrUing Apache Modules with Perl and C 
(http;//www.oreillyxom/catalog/wrapmod/)- 

Eivj\bling Server Side Lncludes: Directory Access 

Our next search result for "Inciudcs", of which I’ve 
.snippeted only the relevant is below. It contains the 
configuration for a specific directory on our machine, nameiy 
/Library/WebServer/Documents. Of more importance, as a 
concept, is the i>kx:k" or “coniainer'' - die directives within 
<Directory> only apply to die location specified. Apache has a 
number of block directives, which you 11 see more of as the 
columns progress. 

<Directory ”/Libraty/WebServer/Documents"> 
may ^ls4> l>c ' ".or niiy oimhin:ition of 

# "Indexes". "Includes^ “FollowSyinLinks^ "ExccCGF, 

^ or‘'Muiii Views'". 

Options Indexes FollovSysnLinks MnitiVlews 

AllowOverride None 

Order allnv.deny 

Allow front all 
</Dlreciory> 

The configcired directory is also ApaehcY DocumentRoot - 
die default location from which files will be served. 
http’Y/127.0.0.1/demo/litioii.htnil. for instance, would reference the 
file located at /Library/WebSmer/Doi^mente/d€m<yiitbn.h(tm 
While we wain’t be getting into the details of the other directives 
above (yet), we need to add Includes to the Options line, like so: 

Options Indexes FallowSymfUnks Mult I Views Includes 
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By adding Includes, we Ye instructing Apache lo allow' SSfs 
within that directory and all it’s childre^n. If we wanted to 
support SSI’s in only a certain subdirectory, w^e'd need to add a 
new <Directory> block entirely. Take the example helnw', which 
ensures that only Aestbed/ (and it’s children) are privileged. We 
don’t have to specify the other directives, like AllowOverride, 
Order, and Allow, as thQ.se are inherited from the parent. 
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<Directory "/Library/WebServer/Docuraents") 

Optlotis indexes FollnwSyraLinks HultiViews 
AllowOverride None 
Order allow,deny 
Allow froHi all 
</Directory> 

^Dlt^scto^y "/Library/WebServer/Docuaents/teatbed*) 

Options Includes 
</j}irectory> 

WeVe still got a little more to go before we're up ajici 
running. Let's move on. 

Enabling Server Side Includes: Associating a Handijer 

As we’ll see in the second half of our article, using an SSI is a 
simple matter of including a special bit of code in your nomial 
H'FML. Vais code lias to be interpreted by the SSI module, and the 
final l)it of HTML (sans tlitxse special axles) is spit out to the 
browser To interpret these codes, we need to tell Ajrache to 
assocLite certain files with the SSI module. Ibis is where the last 
part of our coofigiinition lies, and ts our next releuant search result: 

# If you w:mt U> use itcrvcr side includes, or CGI outside 

# ScriptAliaseii directories, uncomment tbe following lines. 

# 

#To use CGI scripts: 

# 

# Addikiidler cgi-script .cgi 


# To use server-parsed HTML files 

# 

* Addiypc text/btmj .shtml 
^AddHaodkr server-parsed .shtml 

Well cover CGI next moniic concern ytiurself only widi 
the last two lines. Both are commented (indicated by the # 
character that precedes them), and both help the final part of our 
configuration. The first ctjmmand tells Apache that when a file 
with the extension shtml has been requested, the server should 
send a MIME type of text/html. "Ibis, in effect, treats all shtml files 
as if they were normal hlml (which, after parsing, they will l:)e). 

The next line is what actually associates shtml files with the 
SSI module. When someone requests one of these files, it will lie 
bandied" by the server-parsed extension of Apache. When the 
handler is done, the completed resulLs will l>e sent as a text/html 
file to the requesting user-agent (ie. your visitor's browser). 

To finally enable SSIs, uncomment these last two lines, than 
restart tlie Apache web server (either through the Sbatin^ 
System Preference, or with sudo apachecti restart). Once Apache 
hu.s restarted successfully, we can finally move on to something 
demonstrative. 

PiAYiNG With Server Side Includes: Our First Attemft 

We’re now going to create two files. The first will be the 
"sheir that includes some outside data, and the second file will 
be the outside data itself. Open your favorite text editor, add the 
following into a document called index.shtml, and save that file 
into /Library/WebServer/Documents; 

<html> 

<head> 

<t!tle>Quote Selectot</tltle> 


</head> 

<body> 

<lil>Quote Selecto!r</hl> 

<blockquote) 

<MmcIude virTual=“qiiott'.sluml“ -> 

</blockquote> 

</body> 

</htinl> 

Note that our filename has an extension of shtml 
(index.shtml), which was what we configured our ^SSI haiidler fon 
If we had ended the file with an hlml extension (indexbtml), our 
special codes would be heartlessly ignored. Speaking of special 
codes, our newly created file also contains our first intriKlucfion, 
Let's dissect wliat we see: 

• This SSI statement and, in fad, all SSI statemenLs, are encased 
in an HTML comment tag. If you accidentally include one in 
a Ole that is not handled by the SSI module, you can always 
'View HTMI. source” in your browser anti see the statements 
unchanged. Tliis becomes an important barometer: if your 
SSIs aren’t working, then "^view source" and see if they’re 
being interpreted at all. If they are, theyll disappear from the 
final browser output - if they’re not, you'll see them as 
normal HTML commenm. 

• After the opening comment tag, a # immediately appears. No 
spaces should exist Ixftween the two - if some do, then your 
SSI statement won't l>e interpreted correctly. 

• We virtually include a file, quote.shtml, which doesn't yet exist. 
As specified, this file will be in the current diiectory {being 
/Library/WebServer/Documents). We can also use the standard 
.. shortcut to point to files outside the current location. 

Before we create our second file, load 
http://127,0.0.1/mdex.shtrTil in your browser. You'll be greeted by 
the error message in Figure 1. 'Lhe cause of the error should be 
obvious: since quote.shtml doesn't exist, our first attempt at an 
SSI directive failed miserably. 


Quote SeJeetor 

A ) [ + I 0 hup://127,0.0, 


Quote Selector 


i 


\m ciTiir nccumnl while pntccssinj' ihis directive] 


Figure 1: The noi-so-prelty default SSI em)r message. 


A rarely used feaaire of SSI, however, Is the ability to 
customize this ermr me.ssage. Too many times have I visited sites 
and seen this error chuckling at the ineptitude of the web 
master It's well-founded mirth, especially when the fix is mighty 
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inindiess - as we can see below, we can customize the error 
message (with or without embedded HI M I,) for as many 
different uses as we need, 

<h^ad> 

<title>Quote Selector</titte> 

</head> 

<body> 

<hl>QuotG SelectorC/hl) 

<biockcjiK)te> 

crrjn!^="Bali! Quote.shtnii tItX’S tioi exisi 
<!-frijlc;iudc virlliJLl=‘i|tioie.aimiir’ -> 

errmfig=’'<br>Ouch! Nor does qutJte2.shtn>ir"> 

<f-#inclii(k virtiial='’t|uote 2 . 2 dirml" -> 

< /bltJC!kquol:£3> 

</body> 


An example of this output is shown in Figure 2. 



f igure 2 : Customized SS! error messages for mining files. 


Let's create our quotG.shtml, saving into 
/Library/WebServer/Documents: 

Toynbee Idea 
<br>In Kubrick's ZOOl 
<br>Resurrects Dead 
<br>Oii Planet Jupiter 

With the new file in place, reloading our browser shows 
us Figure 3- Note that we didn’t acmally need to name our 
data file with the shtml extension (like quote.shtmf) - only the 
file that contains actual SSI statements need follow that 
restriction {so quote Jxt, quote.ssi and quote.mclude would all 
have been viable alrernarives). Well be expanding quote,shtml 
with ifs own SSLs shortly. 



’Quote SdlfeEXar ■;; 



Quote Selector 


Tovnhee hka 
in kwboci‘% mi 

Dcndl 

On Flanct liqiatcT 





Figure 3: Success! Our first SSI is working as we inlend. 

Now, for literal purposes, this demonstration is winning 
no awards. The raw capahility of SSI’s, as weVc menlioncd, 
works best when combined with navigational elements, 



Eaiy 

Make Drawino Fun on on 

Introducing EazyDraw - the fun, easy-to-use Mac OS X 
design tool that lets you draw like a prol Now you 
don't need to be a graphic artist to create great 
illustrations. EazyDrsw's vfector-based graphics and 
editing capabilities make it easy to create technical 
diagrams, flow charts, and business communications 
as well as commercial line art illustrations and graphic 
elements for application software and web design. 

Learn more about EazyOraw today! Get big savings 
buying direct from our online store. Visit us at 

www.eazydraw.ocim 

(That's easy with a Zf. 

« 2003 Dekorrfl OutiCs, LLC- All rights rcssr^KL 
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Mac aiiri for "S ara trsdefnarics ol Appla Computer, Inc, 


Draw 
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copyriglit wtalenicriLs, etc. continue on with something a 
little more complicated 

PiAYiNG With Server Side Includes: 

CONDinONAIJJ AND QUERIES 

WeVe named our example ‘Quote Selector” tor a reason: 
we\[ like to offer a few different t|uoles that people ran click on, 
but we doift want to have one [)age for each quote (like we 
would with quote!,html, quote2,htmf quote3,htmi, etc.). We can do 
this easily ent)ugh with SSI conditionals and GET queries. 

When you’re submitting data through a web browser (as in 
typing your address into a form at Amazon, or choosing different 
resull sets from a database listing), youYe transmitting the data 
in one of two ways: GET or POST. GET's arc for general-purpose 
forms, and are often used when yoiiVe simply requesting 
information; a searc’h result from Cjot)gle or a ejnety match from 
a ilatal>ase. You can always tell wlicn yt)uVc just used a GET 
form, tecause the resultant UKI will contain the information you 
submitted. For instance, searching for ^I'jiozombie soda'’ creates 
a URL like http://google.com/search?q=biozombie+soda, where a value 
of biozombie+soda was assigned to a variable named q. 

Ilie prime Ixmefit of GET is that yrni am bfxjkmark the 
alK)ve IJRL and revisit it at a later date. POST's, on the other 
hand, are genemlly used when tlie site is requesting a lot of data 
(like a ciit-and-paste of your higlvschool transcript). Unlike GET, 
tlie information submitted with POST is not tnin.smiTted in the 
URL, .so it’s not sometliing readily recreated. 

We’re going to edit our two files so that they’ll retum diflerent 
c|uotes depending on the contents of a GET query'. Keplace your 
existing index.shlml with the following, which we’ve added a 
selectable list of qiicjtes to, Vjxch quote is linked to the current 
d(xaiment (since there’s no filename sfDecifled), and passes a certain 
value ihmugh a GET c|uety (citlier qOI or q02 - even iliough they 
don’t have values, they’ll be p^issed in our query strijig). 

<head> 

<title>Qaote SelectDr</l:itIe) 

</head> 

<body> 

<hl)Qut>Le Selec tor</hl> 

<h2>Choose a quote: <^/h2> 

<ui> 

<li><a bref="?qOl''>On pavement .</a></li> 

<ll><a href="7qD2" >On papyrus. C/aX/11> 

</ul> 

<blockquotc> 

<MiQdudc vimial="qiiotc.iihtini” 

</blockquote> 

</body> 

And replace your existing quote.shtml whth this next 
iteration, which contains a couple of noticeable additions, most 
prominent of which is a set of conditionals for Le.sting against the 
value of $QUERY_STRING. Conveniently enough, the 
$QUERY_STRING is the entire value of the GET that would be 


sulrmitLed from our newly revised index.shtml. If neither quote 
was chosen (ie. tliis was our reader’s first visit to the page), ilicn 
we spit out a quick warning that no quote has been chosen. 

<!^f expi^TSQUEKy_STR[NG\" ^ VqOlV" -> 

TQytitiee Idea 
<br!>lii Xubrick's 2001 
<br>K€surrects Dead 
<bE:>0n Planet Jupiter 

<!^eUf expr=TSQlTERY_STRTNCY = \''q02\"" -> 

That is tifit dead 
Cbt)which tan eternal lie 
<br>And with strange aeons 
<br>even death may die 

<l->^elir expr=TSQUl:KY_SrRLNG\" = V\'*' -> 

No quote has been selected! 

<i-etndir-> 

Figure 4 shows the second quote having being seleaed, 
and the generated URL. 

. qifOKStIttior 

rT^jA AlfTtPR e http; f m 

Quote Selector 

Choose a quote: 

• On 

Itisil bi nut ikud 
^ tiici!) c;iii ctcufiul lie 
Ami with uccn^ 

even dir;]tb nthy die 



Figure 4: Our second quote dLpla]fed- notice the 


71iereis still more useful things you can do with tliis sort of 
structure: I’ve written Ixfore on using this technique to allow 
end users to cuslonme positioning, specific stylesheets (which 
could radically change the layout, colors, fonts, etc.) and so 
fortli, all with{)ui requiring the need of a cookie, and all choices 
being l)cx)kniarkai)ie frt)m computer to computer Read more al 
“Allowing Simplistic User Preferences with SSI" 
(http://hacks.oreilly.eom/pub/h/226). 

fvc also recently used this technic]ue in my header files to 
change the logo that appears based on the specific URL (ie. 
example,com/category1/would have a different logo than 
example.com/category2/). To implement this, you’d use a few 
other tricks of SSI, namely the $DOCUMENT_URI variable, wliich 
contains the curremly requested URL, as well as SSI’s own getter 
(echo) and setter (set) methods. A quick example is below: 

expr="SDO(:tjMBNT_l]RI = /btMjbi^and rriated/" -> 
var^' tieader' \'aliie=1ieaderJ->noks.gif'-> 

<!^Uf expr='’$[XX^lI,V[ENTjm = /a^mics^and^zincs/' -> 

<!-#set v3r^"hcadGr valiie-’'bcader_comics.giP'-> 

<!-’^=dse -> 

<!-#set vai^'’headee vahTe=aieader_main.^-> 

<!^^ndif -> 
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<±mg s r c=■ / ima ge s / < !-#ccIk> var="bcader"“>' 

wldth="445" height^'^O" align="Blddle" hspace=''5"> 


There are Users 


Seeing that I'm nmning out of .space, it's best for me to link 
to some other SSI relaicd hackery Fve written, all of which 
demonstrate certain functionalities iVe deigned to ignore here. 
''More Server Side 'rrickery^* (http://hadcs.oreillyxom/pub/h/222) 
covers cheap iLsername and password authentication, different 
images or greetings depending on the airrent time, and server 
side hit counters and the powers of exec. A “Sc^arcii Engine 
Friendly Image Gallery'' (http://hacks.ofeilly.Com/pub/h/225), 
however, is a "fthl application", much like the quote selector 
above. It denioastnites how to use one SST file to showcase an 
infinite number of images, with error correction, file size, 
modification times, and more. 





and Losers... 


Finishing Up: Ways To Make Things BEum 

You may have noticed tliat weVe been referring to 
http://127.0.0. l/index^shtml instead of the cleaner http://l 27.0.0.1/. 
Depending on whether you deleted tfte default web server files 
or not, you may have received an error message or directory 
listing when you requested the shorter URL. Wliy doesn’t 
index.shtml display when we don't specifically request a 
document (as in http://127.0.0,1/ or http://127.0.0,1/testbed/)? The 
answer, in a wtjrd: Directory Index. 

Apache's Oirectorylndex controls which files it should 
consider the default document for a directory - in other worcls, 
what should be served when no other file has been rec|uested. 
By default, this is normally just index.html, l)ut you can include 
as many fallbacks as you wish, as per die following example: 

MrectoryTttdex Index.shtml index.htmi index.cgi default-htm 

When youVe editing this line in /elc/httpd/httpd.conf, be sure 
to list die file names in order of preference and usage: if you're 
going to be using default.htm more often than index.cgi, move 
that to earlier in the list. Youll get small performance gaias f>y 
sorting coaectly like this as Apache won’t liave to look through 
the entire list for each rec|uest. 

Homework Maijgnments 

Id our next column, we'll chat alxiut CGI: what it is, how to 
enable it, how Uj code for it, how to implement scripts you find 
on the 'net, and aU the rigmarole and hilarity that ensues. If we 
have room, well also talk about how to remove the need for file 
extensions, definitely an important step to good URL design (see 
our first column). For now, students may contact die teacher at 
morbus@disobey.com. 

• “I pity any" what '‘who isn't me tonight”? 

• What other inventive things can SSI lye used for? 

• Tlie quotes in our examples: where'd they come from? 

• Ever seen Biozombi^ Any similar suggestion.s? 


Which 
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SCRIPTING 

WITHIN 

APPLICATIONS 


By David Linker 


Scripting Nisus Writer Express 



Writing perl macros to add functionality 


New oppORTUNniES wnn Mac OS X 

Although we have all read about how the diange from OS 
9 to OS X has challenged developers as they adapt their 
programs to either Carbon or Cocoa, the addition of BSD has 
added a number of powerful tools that can be accessed from or 
added to applicaikms. An example of tills is the powerful word* 
processing program Nisus Writer, which is especially well suited 
for writing in foreign languages, and has a very powerful macro 
programming language. The current version runs in Classic, but 
the programmers are liad at work on a Cocoa version, and have 
released a new version, which titey call Nisus Writer Express, 
This version Ls available for evaluation as a free download, at 
<http://www*nisus,com/Express/>. 

A PERL BY ANY OTHER NAME 

One of the interesting design decisions that the 
programmers made was tliat they incoqx>rated the ability to run 
[)crl scripts as a macro language, Perl is an interpreted language 
that is now included on every Macintosh as part of OS X. The 
name "perr comes from Traaical Extraction and Report 
Language", and in the words of the docunienLatit>n "Perl is a 
language optiini:£ed for scanning arbitrary text files, extracting 
information from those text files, and printing reports based on 
that information." ft has been around since 1987, and is a favorite 
of many for proces^sing text flies. It has a rich set of text 
prtx:ess[ng capabilities, many useful libraries, and an active 
community of users. As such, it is an excellent choice for a 
macro language. 

In order to try out the capabilities of this new type of macro 
extensibility, and learn a little about perl in die prtKess, I 
decided to add back a simplified version of a feature of the 
Classic version of Nisus that is coirrenlly lacking in Nisus Writer 
Express, namely the mail meige function. 

In the prtKess of implementing this funaionality, we can 
learn about how the programmers of Nisus Writer have connected 
jX-tI and Nisus, and also learn a little about perl programming. 


Making a Macro 

Assuming you have installed the Nisus Writer Express beta, 
we can start making a perl macro. Start up Nisus Writer Express, 
which we will call NWE from now on. After it has started up, 
select ’’New Perl Script" from the Macro menu. In the window 
that comes up, type in the following: 

#!/usr/bin/peri 

Mucru Block 
ffMJurcc front 
*dc^Ln:it]oa new 
#End Nisus M^ro Block 

us€ strict; 
use vsruing0: 

print *Mail merge coding soonM; 

Save this by choosing "Save as Macro..." from the "Macro" 
menu. In the dialog that comes up, you will need 10 choose 
"Nisus Perl Macro" from the file fonnat ptip-up, and the "UTF-8" 
choice from the text encoding. You should choose the name, 
which should be "Mail Merge.pl". Note that the extension should 
be filled in automatically if you have chtxsen the perl macro 
format. Check that the destination for the file is the 
/Users/<user_home>/Library/Application Suppoit/Nisus Writer 
Express/Macros, where “<user_home>" represents where your 
user directory is, and save the file. 

Now, we will try running the file before we dissect it. 
Choose "Mail Merge" from the macro menu. A new window 
should cjpen up, and the line "Mail merge coming soon!" should 
be written in it. 

Now, we will look at how this works. Tlie first point to 
understand is that any line that starts with a pound sign is 
considered a comment, and is ignored by the perl interpreter. 
This means that the first line is a rammenl, but this is interpreted 
by the shell as instructions on where to find the interpreter for 
the script, which in thi.s case is perl In the case of a Nisus perl 
macro, this is not actually necessary, since NWE knows that a 
macro with the ".pi" extension is to be executed as perl, but it is 
good form to include it since all other perl scripts outside of 
NWE will need this line to function properly, 


I>avid b a collector of computer languages, having programmed in Algol*60, Fortran IV, Pascal. Basic, lisp, Forth, Logo, Modula-2, java, and varioas 
flavors of assembly. He has also written some C, but tries not to admit it. lie is currently tc-aching himself Objecthre-C, and scripting under Mac OS X. 
You can reach him at dtlinker@mac.coni. 
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The next four lines are special comments that 
communicate with NWE to help set up the environment in 
which the macro runs. These take the form of a number of 
optional commands. The first line, “Nisus Macro Block**, 
defines the be^inninj^ of these instructions. The command 
**soiirce*’ defines where standard input will come from. The 
options are to take it from the front window (front), the 
window below the front window (next), the clipboard 
(clipboard), nr no input (none). The next line is the 
command “destination**, which defines where standard 
output will go, which includes the same options as the 
“source” command, with one additon, which opens a new 
window for output, with the “new*’ option. Tf no other option 
is specified, the output is appended to the end of the current 
contents. If you want to replace the current contents, you add 
the “replace” option. The “End Nisus Macro Block”, ends 
the Nisus commands section. 

The next two lines are commands to the perl compiler, 
which control how it handles ambiguous situations. The first, 
“use strict", invokes some error checking, such as making sure 
tha! variables are declared before they are used. This can be 
very helpful, since if you don't use this option and you type a 
variable name incorrectly, it will just create a new variable, 
introducing a hard to find error. The second reports warnings, 
which include use of uninitialized variables, dropped 
variables, using closed or undefined file handles, among 
others. These commands are not necessary, but are often 
recommended to learners of perl, like myself, in order to 
enforce good programming practices. 

Finally we get to the action statement, which is a simple 
print statement that prints a string. 

Merging umi 

We are now ready to write our first version of the mail 
merge function. We will try to duplicate the original mall meige 
function of Nisus Writer. There were two files that liad io be 
created. There was a template document and the merge file. The 
template document had all of the common text, with the variable 
text replaced by keywords surrounded by “irLternational quote 
marks", or * and «, also known as a left and right guillemot 
(which is also the name of a bird. Go figure!). You can type the 

by pressing the option key, and then the backslash, or 
“<option>A*'. The can be typed by pressing “<option>- 
<shift>-\”. Tlie merge dexument in its simplest form consists of 
comma-delimited text, with the first line containing the 
keywords, and subsequent lines Che text to be substituted for 
each keyword, with each line representing a different copy of 
the template. 

With this in mind, we will create a new version of the 
macro, which will imbed the template In the macro itself, and 
read the merge file from the front window. Reading in a 
template is more complex, and we will deal with dial later. The 
output will be put in a new window. With that in mind, type in 
the following and save it. 


#! /usc/bin/perl 

»Nisus Macm Block 
*somce from 
*dcstlnaTi<Hi new 
*End Nisus Macro Block 

use strict; 
use warnings; 

my ttemplate “ {"Dear Cflrstnaine>, \n" . 
"Thank you for the you gave tneAn"); 

my @mergefiie ^ <STDIN>: 

my $Iine = ^ Holder for temp strinp 

foreach $line (Smergefile) [ 
chomp ($llne); 

] 


ray @keywords - split (/*/*Sniergeflle[0]); 

fareach $linc (ikeyvards) I 
$iine = •€' 

) 

for tiny $i-l: Si<@niergefile; $i++J ( 
ray @copy = itemplate; 
my @subst = split(/A ,StQergefile [$i]): 
for (my $j = 0: Sj < t 

for (my $k = 0: $k<@copy; 1 

$CQpyl$k] — n/$keywords i$jl/$sub6tl$k]/g; 
! 

) 

print @copy; 
print "\n\ii'*; 

I 


Now wc need to create the merge document. Open a new 
window, and type the following: 

flrstname.glft 
Joe.stuffed moose 
Bab,old barrel 

If you want, you can save this file as a text file. 

Now, with that file as tlic foreground file, run your macro 
from the macro menu. You should get the following output: 

Dear Joe, 

Thank you for the stuffed moose you gave me. 

Dear Bob* 

Thank you for the old barrel you gave me. 

Let's see how this works. 7lie beginning and set-up are the 
same as before. We ilien create an array of strings that holds 
the template. The “my" keyword defines die folkiwing variable 
lo be IcKal to the enclosing block. A variable that starts wiili a 
“$” is a .scalar, or single variable, w^hich can hold a number or 
string. A variable that slart.s with a on the other hand, is 
an array, which can also hold numbers or strings. In this case, 
we are declaring a kx:al array variable named ©template, and 
assigning two strings lo this array. Note that the strings are 
surrounded by double quotes rather than the single quotes we 
used in our first version. If we use single quotes, the strings are 
used exactly as they are typed. When we use double quotes, 
the enclosed string is interpreted by a process called 


52 


ScRiniNG Nisus Whiter Express 


MacJ'ech • August 2003 














■ Software goes online 

Electronic Software Distribution 
safely protected by WIBU-KEY. 

■ Pay-Per-Use 

Usage dependent accounting of 
your software. 


■ License Management 

You can easily and flexibly create and 
manage network licenses. 

■ Mac OS 9 & X 

WIBU-KEY supports Mac OS, Windows 
and heterogeneous networks. 

Pfrjt;(=x-t;fon fvff 


The Key is in Your Hands! 


UIBU 

SYSTEMS 




wiBu-sYSTEMsusAjf>L \i\/ \i\! \!M t-L-l L [X Lxi 

Seattle, WA9B101 
email: Ihfo^wibu.com 


W WV\l .V\I tb Lt.CU L'u 


Telt Kits also available at: 

Belgium wibu^impakube, Dormnark: leariOdaribit.dk, Finland fir^abyi^sdtln^byta.i^ni, franca InfoAnaoLlr, Hungary InrfoOmnott.hu, Japan InfaOsuncarFa.co.jp. 
Jordan, bEbation ftarsaft$cvb«r(a.netlb. Kofm dbklmmewibu^o.kc Luxambourg wlbiiajnirwlct.be, NsibeHaods wlbuAimpdki.ba, 

Portugal dubJtCduiJtt.pFt, Thailand preechaOdptf-th com, Unil&d Kingdom irrfp««dework.com, USA $al0i»griftech.cofn 


What does software protection 
have to do with money? 


WIBU-KEY Software Protection 
























“inteipolation" in the perl docmnents. Any included variaf^ie 
names are evaluated, and the result placed in the string. Also, 
special sequences are replaced. We use this characteristic 
using the combination to indicate to iasert a carriage return 
after each line. 

Next, we create anolher local array variable, and use it to 
read from STDIN, the standard input, which has lx:en set to read 
from the front window. We use a trick in peri which is that we 
can read an entire file with one statement into an array, and it 
will be automatically split into lines. Each line will still have the 
carriage return at the end, which can mess us up if we don't 
remove it. We do this in the foreach loop, using the chomp 
function, vvliich removes llie last cliaracler of a string. The 
foreach function is like a for loop but without explicitly indexing 
every element in the army. In this case, the variable $line is 
assigned to each of the elements in tlie army @ mergeftle in order, 
and changing $line will result in changing the array element. This 
frees us from the indexing details. 

We then need to find the keywords from the first Hoe of 
mergeftle array. To do this, we use tlie spilt function. It takes two 
arguments. Tlie first consists of a deliniiterj followed by what 
sequence of characters .signifies a split point, fallowed by the 
delimiter again. In our case, the comma is .signified as our splii 
character Ihe second argument is a string which is to be split. 
Tlie function returns an array containing the fragments that 
resulted from the split, in this case, the keywords. We then add 
the internationai quotes to each of the keywords, so tliat we will 
find the keywords only when they are c.x>niamed within the 
international quotes. 

We are then ready to process the merge file data. This is 
done with a set of nested for loops. Note that if we use an 
array identifier in a context which calls for a single (scalar) 
variable, it returns the number of elements in the array. In 
order to access array elements, we use the array name 
preceded by a and followed by st|uare brackets enclosing 
the index, which stans with zero. The first for loop is repeated 
with each line of the merge data, and creates the array of 
strings that will replace the keywords. In ii, we make a copy 
of the template to work on, and split the string with tlie 
merge data in it. We next have loops for each substitution, 
and for eacli line in ihe template. In ihe inside of the loop, 
we perform the actual substitution, using the "s'" command. 
Tlie means '^operate on the variable to the left, and then 
replace it wiili the result on the nghi"'. Tlie portion between 
the first tw'o slashes is tlie string to match, while the second 
portion is what will replace it. Each of these portions is 
treated as if it were a string in double quotes, meaning that it 
is interpolated. This means that variables are replaced with 
their values. The “g" at the end means to repeat the 
subsLiLuiitm as many times as possible. 

Adding Fljexibiuxy and Siyle 

The version we have lacks flexibility, because to change 
the template text we have to change the macro, ft would be 


belter if the macro read the template text from a file. A perl 
macro in Nisus can read data from a file, from the front 
window, from the next window, or the clipboard. We could put 
the template in one of these locations, but we would need to 
lie certain that either tlie cliplx)ard contains the correct data, or 
that we have the correct windows open and in tlie correct 
order. In order to keep things simpler and more reliable, we 
will instead use a file for the templale in combination with the 
front window as the merge file. 

A .second deficiency is the lack of the ability to use 
different fonts and styles. Perl is designed for plain text, and 
when if is reading from the window within Nisus it only 
extracts the text, without any font or style inibrmation. One 
way we can convert all of the style and font information to 
plain text is to save the file as RTF, wiilcli is a text 
representation including all the page setup, font and style 
information. If we do iht.s, we can turn our previous decision 
to save the template as a text file to our advantage. 

A deficiency of using perl tills way is that we can't have user 
input U) a iimning perl script. We would like to be able to 
specify where the merge template file is, hut if we include it in 
the merge data file, it would be different than the syntax of the 
previou.s version of Nisus uses for its mail merge function, which 
we are trying to emulate. Instead, we will us a builL~in feature of 
the NWE implementation of perl to find the merge template in 
the same loc:aiion as the merge file. 

The NWE allows us to get the full path to the file 
associated wiili the frontmost window in the second element 
of a special array, as $ARGV[1] . This array is normally used in 
perl to access command line options, and if there is no front 
window, or the front window has not been saved, the array 
will be empty. If 1 have a file named “test.rtf in the 
DrjcumenLs folder of my home directory Cdtlinker), the path 
will be ""/Users/dtlinker/Documcnts/test.rtl^ We use this string 
to con-stRict the file name and path for the template and 
output files. 

So, enter the following in Nisus Writer Express, and save to 
your Dcxniments folder as '*Merge template.rtf', in RTF format. 
Note that the keyword for the firstname Ls in bold, and the 
keyword for the gift is in italic and in a larger font size, to 
demonstrate font style changes. When you change tliese, be 
careful to include the international quotes on either side when 
you change the size or style. 

Pear efirstnames^, 

Thank you foi the <gifts- you nie. 

We also need to decide where to send the output. Tlie 
output will be an RIT file, which means that if we just send it to 
a window, wc will get all of the unintelligible formal 
specifications. We could do this, and tlicn save the file with an 
“.rtf suffix, and then open it again to see the changes, but this 
would add extra steps. Theoretically, we could alternatively use 
the NLsy.s perl macro directive "#Send Text as RTP, and gel tlie 
formatting interpreted correaly in the window, but when I tried 
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this I mn into erratic behavior So, we wLD save the output 
directly to a file with the “.rTP suffix, to avoid these problems. 
This will also avoid the extra step of saving and reopening the 
window with the results. 

So, the plan is to read the template from an RTF file, 
process it using the merge file which is located in the front 
window, and then save die output to another RTF file. There 
is just one other change chat we need to make. When we 
save a keyword of the format “-keyword*" as RTF, the 
international quotes are altered to the special codes, "\'c7" 
and “\’c8’\ This means chat what we are going to look for is 
a string"\Wkeyword\^c8". 

Now, things start to get complicated. The character or 
backslash is special in perl, and is the escape character, which 
means that tlie next character is the be interpreted in a special 
way. So, in order to get a backslash, we need to use two tn a 
mw. Now, recall that the string in the substitution command s Ls 
interpolated. This means that we need two backslashes In a row 
to get one in the search string. Since the search string is 
interpolated, and double quoted strings are interpolated, in 
order to get a single backslash we need to have four backslashes 
in a rowt 

Bms AND WHISTLES 

There are a few mt>re final details we need to take care 
of. The first is error detection and handling. The main errors 
that can occur are when we open a file, or when we try to 
find the path associated with the front window. We can trap 
these errors by using the return value of the open function, 
and the die function, lliis will send the subsequent message 
to STDERR, or the standard error output, and then exit the 
program. For perl embedded in new, STDERK is output to a 
modal dialog. 

Another trick that adds a nice feature is the ability send a 
command to the shell from within a perl script. 'Ibis is done by 
enclosing the command with backwards slanted single (]uoles, 
located at the upper left of the keyboard on my iBook. The last 
line of this macro opens the resulting output file in NWE using 
this technique. 

The final version is listed bekrw. 

#!/usr/bin/ptrl 

# Mfxgc.pl 

# A maU merge macro (br Ntsus Writer Express 

# wriiten by David T. tinker 
^ 7/1/05 Version 1.1 

# ddiaker@mac.com 

9 

# Uses template and nu^ 6k format of Nisus Classic 

« 

# Save die this 6le in die macro foUkr in the ft^ltlcr 

# <iiscr liomo/libeary/Appliation Support/Ntsus Writer/Macrtus 

# 

# Make a icmpbic file, with the keywords surrounded by 

# guillemots, like this: <keyword*.You can get these diaxsctcrs 
« by using <option>-\ and <optiooxsbift>\. Save the template 
^ file FTF, with the last pan of the name before the extenskm 

# being “ template”. 

« 

# Make a merge data file, with the first line cnasisti ng of the 

# keywords sepamted by commas, then the .■subsequent lines with 
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* the text to sub!)tjcute by Ss/vc the file to the 

» same fuklcr $s the template file, with the same name as the template 

* He. hot without the word “lemplatc". 

m- 

* [jcave this fUe open as the front window, and nm the macro. 

^^Thc output will be opened in a new window, and saved to the 

* same directory as iIk: other fiks. 

* 

« Known bugs: 

* [It^M-med RTF output 

* Dues not handle accented characters in merge dam 

* 

#\^tuable suggestions anrl atldltions hy Kmo^ of the Nlsus list 

♦Nisiis Idacro Block 

^urce front 

*Eud Nisus Macro block 

use strict: 
use warnings; 

* Ts there a front window li]e> and has It been saved? 

if C0ARGV<U f # No arguments means no merge file 

die "Front window not saved, or no front win£low\n": 

I 

* Now. make the name of the input and output files 

my $[iierge_templ3te_file “ SARGV [1]: ^ Get file path 

$Berge_teraplate_file s/\.. 10.31$//; # Remove extension 

my $raerge_output_file = Smerge„teaiplate_file. ’ OUTPUT, rtf *: 
$B>erge_teaplate_fiie “ $merge_ts[iplate_fiie.' templato^rtf *: 

« Read from flie at toot 

□pen CTEMPLATI, '< ’ .$aierge_template_file) 

or die "Unable to open $nierge_template_flle"; 

my ^teiriplate - <TE«PUTE>; 
close(TEMPLATE): 


e o e TelnetLauncher 


Bookmark and Launch your 
Telnet and SSH sessions 
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>Password storage 
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>Specify terminal colors 
>Port forwarding 
>Terminal emulation 


This and much more available from... 

piDog Software 

SimpleKeys - piPop - DockSwap - ScreenShot Plus 

www.pidog.com Info@pidog.cora 


# Read meige data from front window 
my ^merjjefiie “ CSTDIK); 

foreach my $line E^mergeflle) t 
chomp I$line): 

1 

* Extinct the keywords 

my ^keywords = split{/ ,/,$morgefile{Ol); 
foreach my $line (@knyvords) I 
$line= "\\\\*c7".$line."\\\\'c8"r 
I 

# Open the output file 

open COUTFIliEi ’>' *Siierge_output_file) 

or die "Unable to create $merge_output_file": 

#Do tlie actual merge 

for Emy $i=l: $i<@mergeflie:$!++) ( 

my ^copy = gtemplate: # make a local copy to alter 
my 0subBt = split (/,/,$Diergefile[$i]): 
for (my $j = 0: $j < isubst:$]++) I 

for (my $k = 0: $k<dcopy: Sk-H-) ( 

$copy[$kJ =~ s/$keywords [Sjl/Ssubst [$j]/g; 

I 

print OUTFILE #copy: Outjnif the result 

if ($l<ftnergeflle-l) I 

print OUTFTLE * \poge ’ ■ * Insert a page break between ct^es 
I 

close (OUTTILE): 

# let's look at the result 

'open 'S "Sinus Writer Express" "S[iergc_output_file"'; 

To use this macro, you .should make the mei^e data 
document and save it, leaving it as llie front window. If it has 
the name “Mer^e", with any kind of extension, make sure that 
you have your template stored as ‘'Merge template.rtf in the 
same folder as the mei^e data document. If you then run the 
macro and it runs successfully^ there will be no messages, but 
you will liave a file named “Mail Met^^e OtrrPlIXrtf in the same 
folder as the other files, and oj>en as the fa>nl window. 

FintHE IMPROVEMENTS 

This version accomplishes all of our original goals, which 
were to implement the basic funaionality of mail merge, and 
learn some perl in the pitx:css. There are a number of 
improvements that could be added, and deficiencies addressed. 
Some of these are: 

• We could add error checking for input data formats of the 
merge template and merge data. 

• The output is not syntactiailly correct RTFi which leads to 
some format errors when the re.sull is opened in other 
applications. We could fix the RTF by actually parsing tlie 
RTF and only changing the text, and adding page breaks 
between copies. 

■ Accented text in the merge data is not handled properly, 
since extended ASCII, which is read from the merge data 
file, is handled by special ctKlcs in RTF, which is the 
format for the template and output files. Adapting the 
macro to use RTF for the merge data file as well would 
fix this. 
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• We coulci implement other feamres of the mail merge 
language, whicii tndtided conditionals and include files, 
for example. 

Resolirces 

There are a number of resources that I found useful in 
working on this, and which may prove useful to those who wish 
to write peri macros. 

There were two tutorials that I found to be very lieipful Tlie 
most basic, which 1 used most extensively, was at the University 
t)f Leeds site, at: 

<http://www.comp.leeds.ac.uk/Perl/starLhtml> 

A more detailed tutorial tliat 1 also used was found at: 

<http://www.Gbb.org/PickingUpPerl/pickingUppGrLtoc.html> 

Full documentation of perl is available on your Macintosh 
by using the Terminal and typing “man perl” on the command 
line. Tliis accesses the main documentation guide, which also 
has links to the other documentation, A very useful online 
resource for the peri manual pages, dcxmmentation and function 
descriptions, among other things, is found at: 

<http://www.perldoc.com/> 

One of the documentation pages that may be of interest is 
'^perlembed'^, which describes “how to embed perl in your C 
progranf. In addition to tlic documentation, this site also 
contains links to many other sites of interest to perl 


programmers. One that I found quite intriguing is CFAN, or 
“Comprehensive Peri Archive Netwt>rk": 

<http://www.cpan,org/> 

Tliis contains a vast library of library routines for perl. One 
set that 1 looked at for this article was the modules to parse RTF 
files, but these wcruld require independent instaUatioo to be 
used as is, and I fell tliat this would te more complex than I 
wanted for this demonstration. Ihere are even routines for 
accessing URL's over the internet! 

The Nisus Writer Express perl macro usage Ls documented 
in the help file, accessed by the Help menu, then clicking on 
“Macro Menu'", then on “More about Nisus Writer Express 
Macras^ Additional information is included in the release notes 
for Nisus Writer Express, which are accessible from the 
downlmd page at Nisus. 

Finally, an extremely valuable resource for thexse who use 
Nisus Writer is the Dartmouth Nisus list: 

<http://listserv.dartmouth.edu/archives/nisus.html> 

Members on this list are very helpful and knowledgeable 
about Nisus and a wide range of otlier topics. One of the list 
members, Kino, was particularly helpful with suggestions and 
techniques that were used in this macro, including the error 
ciiccking on file Ofx^ning, and the technique of executing a shell 
command to open the result file in a Nisus window. 

I hope that this will spur your interest in perl in general and 
writing perl maaos for Nisus Writer Express in parliculaL Maybe 
you will even be inspired to embed peri funaionality into an 
application you are developing. Have fun! 



Now serving Cocoa 
just the way you want it. 

Training for Mac OS X doesn't have to be the same old fiavor. 
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RECIPES 


By Richard Patterson, Los Angeles, CA 

X Files Carbonara 


Making Navigation Easier for the 
Impatient 


The Good ol* ways 

Before I was coerced into being carbonized, 1 had a simple 
scrap of code 1 could grab and use whenever 1 needed my 
application to create and write a file, 

lon& byteCounter; 

StandardFlleKeply reply» 

FSSpec asciFile; 

short asciFileNun]: 

char 'textData; 

OSErr err = noErr; 


StandardPutFile(■’\pSave Text Data as:". 
npFullLookupTabla.txt". ireply): 
if(reply.sfGood) 

{ 

asciFile = reply.sfFlle: 

FSpDelateCiasclFile): 

// ignore any error caused if there is no such file 

err ^ FSpCreate(&asc±File.'XCEL‘.’TE3tT\ ’1): }* 1 = 

system script */ 

err “ FSpOpenDFt&asciFile, fsCurPerm, SasciFileNum); 
if (err 1= noErr) return err: 

err “ FSWrite(aaciFileNum, &byteCounter * textData): 
if (err != noErr) return err: 

err = FSCloseCasciFileNura): 

return err: 


It couidnl get much more straightforward than that. 'ITiose 
were the days when the Toolbox really made life simpler for a 
programmen It helped me tell the user (generally myselO what he 
was supposed to do and even suggest a default name for the file. 
The only suspect pan of this code was the shortcut method of 
insuring that the file was indeed a virgin file by attempting to delete 
it before (re)creating it. I knew there were more elegant ways to 
let StandardPutFile tell me that the user was replacing an existing 
file radier tlian just creating a brand new one, but most of the time 
1 didn*t care. 1 just wanted to write tlie file and get on witli it. 
(Most of my programming isfor in-house t 4 se only, so 1 can get aimy 
tvUh quick-and-diriy solutions that you should mtly try at home.) 

Recently 1 was desperately trying to debug an After Effects 
plug-in to send images to a film recorder, and I realized the only 


way I was going to be able tell what was going on would be to 
save a file capturing the state of the image at a certain point. I 
don’t write applications that write files all that often, but years 
ago 1 acquired the prejudice that reading and writing files is one 
of the most basic functions the operating system needs to do and 
should therefore be a very simple programming task. So 1 
resurrected a scrap of code designed to save an image buffer as 
a simple Photoshop file and threw it into the soup, 

'Hie next tiling 1 knew 1 was spending two days trying to 
figure out how to replace the method shown above with 
something that would work inside my cariion code running on 
OS-X. I found myself floating around in all kinds of convoluted 
disaissions of Apple Events and Unicode text, i eventually vented 
my frustration on Apple Developer Support whose suggestions for 
furtiicr reading and examples only seemed to complicate what I 
thought 1 was beginning to grasp. Fortunately the support 
technician was very patient, and I was able to crystallize my 
ferment into a rational suggestion tliat OS“X should provide a 
much simpler higher level ftjnction to help tlie less experienced 
programmer create and write a file. The support technician agreed 
that was a gocxl idea^ but indicated that it was ncit at the top of 
their priorites. Wlien I finally saw the light thanks to Mr, KJ, 
Brickneli’s indispensable tome. Carbon Pn}gramming\ 1 realized 
that perhaps 1 shcmld write a sample function that might spare 
someone else tlie agony I had just experienced, 

NON STANDARD 

Tlie functions for opening and writing to a file (FspOpenDF 
and rSWrite) still work in (^rbon on OS-X, but the StandardPutFile 
and StandardGetFile functions have been replaced by Navigation 
Services, The system had just outgrown the functionality provided 
by the Standard File Package. ITiere is a Navigation Services 
function NavPutFile that was the original replacement for 
StandardPutFile, but with OS-X Apple recommends that we use 
NavCreatePutFflaDialog. If 1 had been keeping up, the transition 
from StandardPutFile to NavPutFile to NavCreatePutFileOialog might 
have feen smooth and effortless. Instead I woke up and found 
die following definition staring me in the face: 

OSStatus NavCceatePytFil^ialog ( 

const NavDlalogCreaticmOptionfl * InOptions, 

OSType inFileType. 

OSType InFileCreator. 

NavEventDPP inEvantProc * 


Richard Patterson is in chaige of digital imaging at Illusion Arts, a visual eftects facility in Van Nuys, CA, specializing in matte paintings and bluescreen 
compositing for movies. You can reach liini ai richard@iltusion- 3 rts.com. 
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void * inClientData. 
NavDialogRef * outDialog 
}r 


Then I discovered there were 11 other iunctions I must call 
before I can have an FSSpec to use in the familiar way. 

What I wanted was one function tiiat took care of all the 
user interaaion and just gave me a ready-to-wear FSSpec. It 
would need to know what kind of file I am trying to create, so 
there are three things I need to give it: the fUe type, the file 
creator and a pointer to the FSSpec. 

OSErr ElnipleNavPutFilet OSType flleType. 

OSType fileCreator, 

FSSpec nbeFlleSpec) 
f 

OS S t atus theStat us; 

NavDia10 gRe f theDial o g: 

NavReplyRecord theReply: 

AEDesc aeDesc; 

FSRef fsRefParent, fsRefDelete: 

UnlCbat ‘nameBuffer i 

UniGha rCoun t name Len gt h; 

Flnfo fiielnfq; 

OSErr err = noErr: 

theStatus = NavCreatePutFileDiaiog(NULL. fileType, 
flleCreator, 

NULL. NULL. 

^^theDlalDg); 

NavDiaiogRuti(theDlalog) : 

theStatus NavDialogGetReply [ theDialog, ^theReply): 
NavDialogDisposettbeBialqg): 

ift!theEeply.validRecord) 

( 

//Assuming the user changed hi^er mind? No harm; no ftnil. 

// Still Deed to todicate that a file has not been created 
return * 1j 

) 

err “ AECoerceDescC&theReply.selection. typeFSRef, 

&aeDeac): 

if(err != noErr) return err: 

err = AEGetDeScData(iaeDese, sRefPa rent, sizeof(FSRef))j 

if(err t- noErr) return err: 
naraeLength " 

(UniCherCount)CFStrlngGetLength(theReply.saveFileNaine); 
nameBuffer = (UniChar NewPtr((long)nameLength); 
CFStringGetCharactersCtheRepIy.saveFileName* 

CFR an geMake(0, (long)nameLen gt h), 

^naateBuffer fo]); 

if (nameBuffer = NULL) return -1: //generic error 
if(theKeply.replacing) 

! 

err = FSMaksFSRefUnlcode(&fsRefParent, 
nameLength, nanieBuffer, 

kTextEncodingUtilcodeDe fault. 
ifsRefDelete) : 

if(err “ noErr) err “ FSDeleteObjectC&fsRefDelete); 
if(6rr “ fBsyErr) 

I 

DisposePtr((Ptr)nameBuffer); 
return err; 

I 

I 

err = FSCreateFileUnlcode(&faRefParent. tiameLength. 
nameBuffer. 

kFSCatlnfoNone, NULL. NOLL, 

theFileSpec); 

err = FSpGetFInfo(theFileSpec, &flleInfo): 

filelnfo.fdlype = fileType; 

filelnfo.fdCreator = fileCreator; 

err " FSpSetFInfo(theFileSpec, &filelnfo): 

return err: 

1 


So now my original scrap of code would become: 

long byteCounter; 

StandardFllePeply reply: 

FSSpec asciFile; 

short asclFlleNuut: 

char 'textUata: 

OSErr err = noErr; 


err “ SimpleNavPut File ('TEXT', 'XCEL' JcasciFile); 
if {err ™ noErr) // a file was created 

I 

err “ FSpOpenDF(&asclFile. fsCurPeriu, £iasciFlleNuffi); 
if (err != noErr) return err: 

err ^ FSWrita(asciFileNum. fifbyteCounter. textData); 
if (err !“ noErr) return err: 

err = FSCloeeCasciFileNum): 

) 

return err; 

I've sacrificed a little functionality in tlic dialog, since I can no 
longer suggest a default file name and prompt the forgetful user 
about what he is supposed to be doing. This scrap is fewer lines of 
ccxle than my original, iliougli, and even easier to use, I shall not 
attempt to explain what all the functions are doing in my 
SimpleNavPutFile. M1 can say is that this works on my machine and 
Ls not meant to l)e anyiliing odicr ilian a quick and dirty solution. 
Note tliat it includes tlie call creating tlie file and deals with the 
choice to replace an existing file. It may just amount to the same 
thing as using die now-deprecated NavPutFile, hut 1 Ix^lieve it lets 
OS-X put up die latest and greatest file navigation dialog. 

1 should confess that this solution will fail with OS-9 
bec'ause it gives up if it cannot coeire the AEDesc to an FSRef. 
Bricknell's Ixiok has a discussion on page 960 of how to derive 
the FSSpec in OS-9 when tliis coercion fails. 1 have not included 
it, because my immediate concern was getting over the hump in 
OS-X, and I want to keep this as simple as possible. 

The corresponding SimpleNavGetRle is built around 

OSStatus NavCreuteGetFileDialog ( 

const NavDialogCreationOpcions * inOptions, 
NavTypeListHandle inTypeList. // can be NULL 

NavEventUPP iuEventProc . // can be NULL 

NavPreviewUPP inPreviewProc , // can be NULL 

NavObjectFllterUPP InFiiterProc. // can l>e NULL 
void ' inCllentData, //can he NULL 

NavDialogRef * outMalog 

Most of the parameters which can be set to NUll have system 
defaults that will be used when they are NITL. Setting tlie 
NavTypeListHandte to NUU simply results in no file filtering in tlie dialog. 
In order to avoid dealing with die NavDialogCreationOptbns you can use 
NavGelOeiaultDialogCrBationOptions to set everything to a default. 

SimpleNavGetFile(FSSpec ^theFileSpec) 

[ 

OSStatus cheStatus; 

NavDialoa^tef theDialog: 

NavReplyRecetd theKeply; 

NavDialo^CreationOptions inOptions: 

AEKe ywo rd t h eK s ywo rd; 

DescType nctualType; 

Size actualSize: 

OSErr err = noErr; 

HavGetDefaultDiaiogCreatlonOptioiis(^InOptions): 
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theStatUB - fiavCreateGetFileDialog(&inOptions» 

NULL. miLL. NULL. NULL* NULL, 

^thfeUialog); 

MavDialogRun(theDialog); 

tbeStatus = NavDialogGetReply [ theDialug* litfaeReplyJ; 
NavDialogUlapgseltheUialog); 

if{!theReply*validRecord) 

I 

return *1: 

// Asfaiming ihc itser diangcd his/licr mind? 

// No tiann; no fbuLbm need to know 
// not to iry to ojicn tile ftle. 

I 

// Get a pointer to selected file 
err AEGetNthPtrC&CtheReply.fielectlcm). 1* 

typeFSS, SetheKeywo rd, 
&actualType. theFileSpee. 
sizeof(FSSpee), 

SiactualSize): 

return err; 


SOFTWARE 

LOCALIZATION 

MAOE 


If you want to filter files to limit the optioas provided the 
user m the Navigation Dialog, you can either use an 'open' 
resource created witli a resource editor or you can create a 
NavTypeList. To use an 'open' resource you gel the 
NavTypeListHandle with a GetResoure funaion. 

NavTypeListNandle typet^ist " 

(NavTypoLifitHandlo}GctKesource(^open', 128}^ 

theSiatus = NnvGreateGetEileDialogt&inOptions, 
typeList, 

NULL. NULL. NULL. NULL* 
iitheDialog): 

The 128 is just the number of the resource you have 
created. If no such resource is found typeiist will be given a 
NULL value and you will he doing no file filtering. 

To create your own NavTypelisl from scratch you need 
only fill in a few blanks. 

NavTypeList i nTypeLlst; 

NavTypeLiatPtr infypeLlstPtri 

InTypeList.componentSignature “ kNavGenericSignature; 
InTypeLlat♦osTypeCoum = 1; 
inTypeList.OBTypelO] " 'TEXT*: 

inTypeListFtr * tinTypellBt; 


theStatUS “ NavCreateGetFileUialogC^inOptions* 

HnTypeLiBtPtt. 

NULL. NULL. NULL. NULL. 
tftheDialog) : 

I have used a NavTypelistPtr just to minimize the confusion 
when it is necessary to pass a NavlypelistHandle to 
NavCreaceGetFileDialog. Tlie kNavGenericSignaiure Ls a system 
constant which tells it not to filter files by their creator. If you 
wanted to chcx)se from only Excel files you could put 'XCEL' here 
instead. Since tlie osType is an amty you c’an list several file types 
for a given appliction signature* and you can also make NavTypeList 
iLself an array so tliai tlie handle tells the dialog to display any 
number of file types frum any nuinfx^r of spedfica applications. If 
you need to do diis. though, you are on your own. 



August 2003 • MacTkch 













COCOA TIP 


By Clark Jackson, Tacoma Power 

Using NSParagraphStyle 


How to programmatically set tabs and 
more in an NSTextView 


ITie need to beciome Jicqutiinttid with NSPanigraphSlylc 
oaxirred when 1 aLLcmpted lo automate some reporting. At times 
"enlen>rise” computing stands in contrast to typical “coasumer"* 
computing because the latter is user-cmiric while the former Is 
rL^>orr-c:entnc. For example, consumer computing faciliiates lots of 
user control whereas enterprise computing just wants to-generate- 
reports-unattended-ar-midnighc-thank-you. Since much of the text 
system in Cocoa "just works” for the ilsi% the details of how to let 
the compuler take control in making a report are often left a 
mystery. Let's shed a little light on some of tliat mystery. 

What we need is to know liow to use just one piece of 
Cocoa’s extensive and capable text system that will allow a 
program to format text inside an NSl'extView. 'Ihe key is tLsing 
the NSParagraphStyle class. 

Some preliminaiui-s 

Explaining Interface Builder and Project Builder is )>eyand 
the scope of this article. Suffice it to say, the project uses the 
Model-View-Controller paradigm employing MyModel, 
MyWindowController, and NSTextView classes. Here’s what the 
view looks like: 

eee Window 

f App<yStV**0 f AppVStV«*2> f ApirfyStyteB ) 


The only thing noteworthy about this window is dial it 
contains an NSTextView because that is where our formatted text 
wiD appear. 

To see the results of our formatting it will lie useful to use 
NSTexlView’s ruler To see the ruler it is necessary to add the 
Foniiat menu to our menu bar. 'nierefore, before leaving IB, we 
drag the Format menu onto our project's main menu bar and give 
Show Ruler a key equivalent: 



. 

B3I3EHHHII 

Su&mehti ► 

Edit > 

1 

Hem 

Window ► 

1 

Format ► 



Font 




Atign Left 

Center 

justify 

Afign Right 

1 

Show Ruler 

3ER 

Copy Ruler 

A3gc 

Paste Ruler 



Figure 2. for conwniencef in Interface Builder we drag a 
Formal menu onto the menu bar and giie 
Show Ruler a key equivalent, 


The view 

For our purposes, the important thing to know about 
NSTextView is that the text displayed in an NSTextView is its 
textStorage and that textStorage holds aUrtbiited strings, The 
textStomge is an instance of NSTextStorage which inherits from 
NSAttributedString itself. Attributed strings are Cocoa 
Foundation objects that i:ontain both ordinary NSString's and 
Figure The interface window containing an NSTexiVtew. formatting objects that apply to those strings, for example, 


Clark Jackson test drove the first Mac and recogni/ed that it was about to change the world. Lately he has been busy wearing many hats automating 
energy accounting in the rapidly changing ekclrical power industry at Tacoma Power. He can be contacted at cjackSDn@dtyoftacoma.org, 
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NSFont and NSParagraphStyle. You can bypass dealing with 
NSTextView's textStorage directly, that is, you can 
[jnyNSTextView setString:@’‘aString1, but ©"aSiring" will adopt 
either the default paragraph style or a previous style already 
residing in the textStorage. 

Therefore, in order for text to appear formatted in an 
NSl'extView we have to: 1) create an NSAttributedString instance 
initialized witli the string we want to format, and 2) give that 
NSAttributedString instance the objects that it will use to fonnat 
the string“in this case an NSParagraphStyle object* 'ITiis 
attributed string goes into our NSTextView’s textStorage where it 
appears formatted to die user. 


The Controller 

Tlie interface buttons are connected to the controller’s 
aaions in a typic'al fashion. BasicaUy, each button initiates a 
controller action to dispby a different formatted paragraph in 
the NSTexiView. The controller does this task by sending a siring 
(NSString) to the model object. The model object will return 
attributed strings (NSAttributedString^s attributed with 
NSPamgraphStyle’s) to the controller. Finally, the controller will 
pass the attributed string to the text storage of the NSTextView 
where it will appear formatted to the user* 

Here is one of the duee controller actions; 


applyStykl 

This jneUiuU sets a puumi for the other two belongiog lo the controUcr An 
itnJbf matted string w put in the NSTextVkw for compsirison purposes only The 
pfogrim pflLUies so the user can ace it* Next, the string is sent to the model oh^ct 
which returns h sis an attributed string. Finally, the attributed string goes into tlie 
NSTextView revealing the new format* Refer to the scjuae ut sec die iilhcr two action 
methods, apptyStylc2 and applyStyle3. 

- (IBAction)applyStylel:(id)sender 

i 

HyKodel •thnModel- 

NSAtt ributedString *anAttString: 

KSString 'aStrlng; 

// a siring containing multiple paiagraphs 

aString ” @"0n a »erry-go-round in the night. 

aString = [aString strlngByAppendlngString: 

e^Coriplis was shaken with fright.\n"]i 
aStrlng “ [aString stringByAppendingString: 

e^Despite how he walked. "J: 
aString “ [aString stringByAppendingString; 

§**TVas like he va3 stalkedAn**J; 
aString « [aString stringfiyAppendlngString: 

some fiend always pushing him right."]: 

// limerick by David Morin. Eric Zastow. E'beth HaJeyJohn Golden, and Nadian Salwen. 
// http://www.aps.org/apsnews/11855 -html 

// a convenience method to rcsiorc die default paragraph style to the NSTextView 
[self resetTextVlew]: 

// mstall string wA) changing paragraph style for comparison 
[myNSTextView aetString:aString]: 

[my NSTextView display]: //force redraw 
sleep (1): //iMiuse 

// now conven aString to an NSAitrihutedStriog by applying an NSParagraphStyle 

// using the model o^a 

theModel “ [[HyHodel alloc Unit]: 

anAttString - [theHodel attrihuteStringl:aString]: 

[theModel release]: 

// now that wc have the attributed string, put It into the NSTtoctView. 

// En order to get multiple attributed stri^ into a textStorage use 
// [myNSTextView mscrtlextiattributcdStriitg] instead 
[IroyNSTextView textStorage] 


s etAt t r ibut ed S t r Ing:anAt tS t r in g J: 
[myNSTextView setNeedEDiaplay:YES]: 
retum: 


The Model 

MyModel has a meihcxi for each t^f the ctmuoUer's actions. 
It is here that we make use of NSParagraphStyle. Each method 
takes an ordinary NSString and returns it as an 
NSAttributedString so it can end up formatted in the 
NSTextView, When running the program, click inside the 
NSTextView and make the niler visible* Some of the paragraph 
style attributes that we set show up on the NSTextView's ruler: 



Figure S Many of NSParagraphStyle attributes appear in the ! 
NSTextView mler 

Following are the melhtKls used to create 
NSFaragraphStyle'*s and apply tliem to strings thus creating 
NSAttribuledSuing's: 

auributcStringl 

This meihod creates an NSMutabk-AiiribuicdSrring, lUiing an NSString and an 
NSMutableParagrapbSiylc. 

-CNSMutableAttributedString *) attribureStriugl: 

(NSString *) aString 

NSMutableParagraphstyle ’sHutahleParagraphStyle; 

NSMutableAttributedString *attString: 

r 

The only way to instaniiate an NSMuiabfcPaiagraphStyle is to mutably copy an 
NSttiragraph%le*AiKl since we don't have in existing NS^ragraphSfyle available 
to copy, we use the decide one. 

The defiult v^lms supplied by the default NSParagraphStyle are: 

A%nm<mt NSNaturalTextAlignmctit 
Tab stops 12 left alined tabs, spaced by 28.0 points 
Line mode NSUneBreakayWcMdWrapping 
All others O.Q 
7 

aMutahlePatagraphStyle 

i[NSParagraphStyle defau1tPa ragraphStyla]mutableCopy] : 
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Perforce 


Fast Software Configuration Management www.perforce.com 


Other sv^tems require an army ot cansultants, 
months of hacking, and probably the odd dab 
of cra^y glue. With Perforce, nationwide and 
worldwide development teams can focus on 
working together without worrying about 
holding It together. 

Work anywhm^. Requiring only TCP/lf^ Perforce 
makes use of a well-tuned streaming message protocol 
for syr'Chronking diont workspaces with server 
rcposilorv contents. And the Perforce Proxy offers 
caching to provide remote users with quick download 
tivrm while mairxtaining reakime access to project 
adivity and status infoonation. 


Wdi P&fotcs, the fast way is the right way Install It 
last learn it fast run it fast With other SCM systems, 
developers face an unpleasant choice: do it the right 
way or do (t the fast way Perforce's speed and reach 
mean the fast way is the right way. See how Perforce 
compares with other leading SCM systems at 
htfoyAAWW.perfonoe.conVperforcfi^revif^^ htm I 

Run at fu9 speed even with ht/ndkedb of users and 
mHtmns of fUes At the core off Perfonoe lies a relational 
database with well keyed tables, so rxjrrnal user activity 
can be accomplished in near-zero time. Larger 
i^^eratiocis (like Labeling a release and branching) are 
translated into keyed date aC 3 )ess, giving Perforce the 
scalability that big proiects require. 


Jhity cross piathmn. Perforce runs on more than 
50 operating systems. Including Windows; UNIX’, 
Linux', Mac OS X, AS/400, and more. 


integrate with leading IDEs and defect hadeers: 

Visual Stiidjo,NET, Visual C++\ Visual Basic% 
JBuilder', CodeWafrior, TeamTrack', Bugziila™, 
ControlCentef, DevTrack' packages, plus more. 


Develop and maintam multiple coddmes. Perforce's 
Inter-Rle Braridiing lets you merge new features and 
apply fixes across codelines. Smart metadata keeps 
track of your evolving projects even while they are 
developed in parallel. 









// Now adjim our NSMuuhkhtnigisphStyk fonnatring to be whatever we want- 
i^V^t numerk: valuo below are in points (72 points per inch) 
(aMutabloParagraphStyle 

setAllgniietit ;NSLeftTeittAligiiffieQtI i 
taHutableParagraphStyle setllneSpacingtS.Sl \ 
[aMutabieParagraphStyle setParagraphSpacing:25^5]: 
[aHutableParagraphStyle setHeadlndenttZS.O]; 
[aMutablaParagraphStyle setTailIndenr;-4^>0 ]i 
// setTaiUiKknr if nepiivc, ofisei from right margin (right margin mart does 
ii NOT appear); if positive, offset front left margm (margin marit DOES appear) 

[aMutableParagraphStyle setFirstLinaHesdIndantt65.0]: 
[aHutableParagraphStyle 

setllneBreakHodetNSLineBreakByWordWrappingl: 


r 

possible allignmenis 
NSljcfrThxtAlignmem 
NSRightTextAl ignmeni 
NSCcntctTcxt Alignment 
NSJusUficdToctAJignment 
NSNaturalTcxtAljgnment 

pusribic line wraps 
NSUncBreakllyWonlWiapping 
NSI JnelheakB^ IharWiapping 
NSI i ncBrcakB^ ipping 
V 

// Instantiate the NSMmabkAttribniedString with the argument string 
attString ” [ [NSMutabLeAttributedStrlng alloc] 
initWithString:aStringJ ; 

// Apply your paragraph style att ribute over the enttre string 
fattStrlng ad4Attribute:NSParagraphStyleAttributeHaioe 
value J aMntabl ePa ra grapbStyle 
rangetNSHakoRange{Or[aString length])]; 

[aMntableParagtaphStyle release] j // since it was copy"d 
[attString autoraleasej : //since it wa^ alloc'd 
return attString; 


If your NSTexiView already has attributed strin)?s in its 
ce5aStorage, you can get tJie NSPantgraphSiyle by: 

a!1vitableParagraphStyle “ f [myTextView typingAttributes] 
obJectForKey:t^NSParagraphStyle"]; 

The NSPamgmphSiyle relumed alx)ve comes from the 
attributes of the text from where the cursor is found inside die 
NSlextView. NSParagraphStyle's ean span multiple paragraphs 
but lliere cannot Ix! more tlian one per paragraph. 


3ttfibutc!String2 

ThL^ mcthcHl crcatcii an army of NS't exlTaJi’s and applies them to Uve 
NSMiitahlcParagniphStyle betbre It b used to erexLe the NSMuUbleAitributcdSiring. 

(NSHutableAttrlbutedString *) 
attributeStringZ:(KSString *) aString 

I 

float firstColumninch ^ 1.75, 

otberColumnInch =0-6. pntFerlnch - 72*0: 
int i : 

NSTejttTab 'sTab: 

NSHutablcArray *ttyArrayOfTabs; 

HSMutableParagraphStyle *aMutableParagrapbStyie: 
NSMutableAitributedStrlng •attString; 

myArrayOfTabs = [KSHutableArray arrayWlthGapaclty:14]: 
aTab “ f[NSTextTab alloc] 

initWithType:KSLeftTabStopType 
location;firstColuBnlnch* pntPerInch]: 

[inyArrayOfTabs addOb^ ect; aTab]: 


[aTab releaae]; ff aTab was alloc'd and the array owns it now so release it 

I 

aTab = [[NSTextTab alloc] 

initWithType:NSRlgblTabSt opType 
location:(firstColumnlnch* pntPerTnch) 
t C(float)i * otherColuinnlnch • pntPerlnch)]: 
[myArrayOfTabs addObject;aTab]; 

[aTab release] : // albh was altuc'd and the array owns it now so release it 

I 

r 

possible tab stop types 
NSLcJftTabStopTypc 
NSRightTabStopTYpe 
NSCenierTabStopl ype 
NSDeci malTabStoprypc 
7 

aHutableParagraphStyle “ 

[iNSParagrapb Style defaultParagraphStyie] inutableCopy|: 
laHutablEParagraphStyle setTabStops iiayArrayOfTabs]: 
attString “ [[NSKuliableAttrlbutedString alloc] 
initWithSt ring:aSt ring]; 

[attString addAttribute :NSFaragraphStylBAttributcNaiiia 
value:aHutableParagraphStyle 
range:NSMakeRange(0,[aSt ring length])J: 

[aHutableParagraphStyle releasel: 

[attString autorelease]; 
return attString: 


Tabbed text appears as below without using 
NSParagmphStyle: 
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figure 4. Default behavior (f an NSTextVieuf containing 
tabbed text. 'Ibe tab ipacing i-t arbitrary and the lines wrap 
even though there is sfrace enough to bold llte whole line. 
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Tabbed Icxi appears as below arier ercating an 
N^SMutableParagrapliStyle and assigning it to an 
NSMiitabieAttribiitedStfing using the attribiiteStringZ methoci: 

*#6 0 _Wndow 


( ApfiVSeyk 1 ) I Awi*y Sivl»2 ) { ApplyStyteJ ) 
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Figure 5 By using an NSMutahleParagrapbStyle the tab stops 
haw been precisely set and the lines do not jjjrap unexpectedly. 


jiitribuicSirjng 3 

This method supplies a wuy to pjirse n string eontaining multiple paragraplis and 
apply different paragraph styles to each. 

- (l^SMutabloArray *) attributeStrlngSt (NSString *}aSrring 

f 


NS^snge myRange,rangeOfLine < rangeOfLineCont ent: 
unsigned startTndex,lineEndTtidex.content^Endlndex: 
NSHutableParagraphStyle 

‘aMutabiaParagraphStylel,^a}lutableParagrapbStyle2i 
NSMutableAttributedString 'attString: 
int linaCtr; 

HSMutableArtay ' arrayOfHSMuiableAttributedString; 
KSStrlng • puUedOutParagrsph; 

atrayOfNSHutableAttributedString 

^ (KSMutableArray arrayWithCapacity:5] r 

r 

lines cati be tcrminaied in die following ways for use with 
getLineStan :e[nl :conientsEnd dbrRange: 

* lI+000D(\rorCR),Mac 

' U+202fl (llnicode line separator) 

• U+00f)A (\n or fF). Uow 

- 11+2029 {Unit'ode paragraph separator) 

- \r\n. in ihiii order (also known as OILF), Windows 

V 

r 

1 Ising getl4neSrart:end;contemsEnd:h>rRange: 

©'BigNrNnMae -example string 
in thb ease 

1 St conteotsEndlntltLX is set to 3 ► 

the first charaacr past the line content, 
line content Lieing defined as the diameters not iududing 
line lerminaUon dtamcieits) 

I St lineEndlndex is set to 3 

the first cbacuier past the end of line diaractcKs) 

7 

// make 2 dificirmt paragraph styles 
aMutableParagraphStylel = 
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Then, when you are ready to sell it, you can protect yourself further 

with a licensing agreement. 

I am an attorney practicing in Inteliectual Property, Business Formations, 
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Long Distance 



Exceitent rates on intrastate, intralata/toif calls 
and international colling with no term contract. 


Toll Free (800/888/877/866) service, 
same low per minute rate for incoming calls 


10 cents per minute calling card. 

Deioiled billing directly from Capsule Communications, a Covisto Company. 

Quolity electronic and telephone customr support. 
No monthly billing fee if you sign up for AUTOPAY billing 
option Of if your bill is over $20.00 each month. 
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[[NSParagraphStyle defaultParagrapbStyie]inuiableGopy] : 
aKutablciParagraphStyle^l 

t iKSParagraphStylt? defaultParagiapliStyle]mutableCopy] ; 
[aHutabieFaragraphStylel 
setAligninaTit: NSLeftTeKTAiignntentJ : 
laMutablsParagraphStyie2 

E e t A1 i gnme nt: NS Ri gh tT ext A1 i gntn a n 11 ; 

// initialke 

ntyKange = NSNskeKange(Q.O); //(lodtioti,length) 

UneErid Index = 0; 
lineCtr = 0: 

r 

'llic whilcO bkick below walks down ditr string palling out lines (paragraphs) 
including their end of line (paragraph) eharaeters. converts them to attributed 
strings^ 

and adds them to an array. 

The range in the gctLinc5tan;end;contenrsEndTorRange: merhex) has to be picky 
Jxnn wlierc it's IiKation is hut doesn't have to Ik pieky alxmi length (i.e. 0 will 
do) 

V 

while{lineEndIndex < faStting length]) 

I 

[aString getLineStart; &startlndex 
end: firlineEndIndex 
contentsEnd: StcontentsEndlndex 
torRange: myRange]: 

/f rangcOflineCxjntcnl cxcitidts line termination di(iraeieKs) 
rangeOfLlneContent = 

NSMakeRatige CstartIndex * content sEndIndex-startlndex): 

// rangeOfl.Ene includes line termination diaraeteits) 
ran geOfLine "= 

KEMakeRange(startindex.lineEndlndex startindex): 

// apply paragrapii style to piilledOiitl'iiragmph 
puliedOutParagraph = 

[aString substiringWithRange: rangeOfLine] ; 
attString = [[NSMutableAttributedStEing alloel 
initWithString:pulledOntParagraph] : 
if(liiieCLr % 2 — 0] //alu*rnate paragraph styles on odd/even lines 
I 

// U mngeJungth below is item then the paragraph style is not applied. 

// lk>r strings with length > 0. raiigedetigth should be > d :tnd <= length of the 
// string so \SMi{keRange(i),l) would work jls well IkIow 
// provided you don't have an empty siring. 

[attStriTig addAttrihyta:WEParagraphStyleAttributeNaine 
value; aMutabloParagraphStylel 

range: NEHakcRangotO.[pulIcdOutParagraph length])]: 

I 

else 

[ 

[attString addAttrlbute:NSParagraphStyleAttributeName 
value:aKutableParagraphStyle2 

range’NSMakeRange[0,[pulledOutParagrapb length])] * 

I 

[arrayOfNSMiJt.ableArtrfhuredString addDbjeet;attString] ; 

[at tString rel ease] j // the array now own?; it 

lineCtr+t: 

// leealculiiie die nuige [lelbre looping 
myRange NSMakeRange(lineEndlndex.O) ; 


[aMutiibl eParagraphStyle I release] i 
[aMui£iblePeragraph£tyle2 release]: 
reiurrj arrayOfNSMutabieAttributedStrlng: 


CONCMJSION 

Cocoa’s text system is extensive iiivoiving many classes not 
even mentioned here. But if you just need to get some 
formatted, tabbed text into an NSTextView for that special 
report, the methods explained here should do the trick. 
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Without a doubtf the Premiere Resource Editor 
for the Mae OS ...A wealth of time-saving foo/s,” 

- MacUser Magazine Eddy Awards 

"A distinct improvement over Apple's ResEdit. ” 

- MacTech Magazine 

'Every Mac OS developer should own a copy of Resorcerer 

- Leonard Rosenthof Aladdin Systems 

“Without Resorcerer our localization efforts would look like a 
Tower of Bah(d. Don't do product without Ur 

— Greg Galafios^ CEO and President, Metrowerks 


“Resorcerer's data template system is amazing, '' 

-Bill Good77ian, author of Smaller Installer and Compacl Pro 

“Resorcerer Rocks! Buy it, you will NOT regret if 

- Joe Zobkiw, author of A Fragment of Your Imagination 

“Resorcerer will pay for itself many times over in saved time and effort ," 

- MacUser review 


“The template that disassembles 'PlCT's Ls awesomeU 

- Bill Steinberg, author ofPyro! and PBTools 

“Resorcerer proved indispensible in its own creationr 

- Doug McKenna, author of Resorcerer 






Version 2.0 


ORDERING INFO 


Requires System 7,0 or greater, 
1.5MB RAM, CD-ROM 

Standard price: $256 (decimal) 
Website price: $128 - $256 
(Educational, quantity, or 
other discounts available) 

Includes: Electronic documentation 
60-day Money-Back Guarantee 
Domestic standard shipping 

Payment: Check, PO's, or Visa/MC 
Taxes: Colorado customers only 

Extras (call, fax, or email us): 

COD, FedEx, UPS Blue/Ked, 
International Shipping 

MATHEMA^STHETICS, INC. 

PO Box 298 

Boulder, CO 80806-0298 USA 
Phone: (303) 440-0707 
Fax: (303) 440-0504 
re sorcerer@lm athemaesthetics. com 


The Resource Editor for the Mac ™ OS Wizard 


New 

in 

2 . 0 : 


• Very fast, IlFS browser for viewing; file tree of all volumes 

• Extensibility for now Rcsoreorcr Apprentices (CFM plug-ins) 

• New AppleScript Dictionary (^aete^) Apprentice Editor 

• MacOS 8 Appearance Manager-savvy Control Editor 

• PowerPlant text traits and menu conunand support 

• Conuplete ATFF sound file disassembly template 

• Big-, little-, and even mixed-endian template parsing 

• Auto-backup during file saves; folder attribute editing 

• Ships with PowerPC native, fat, and 68K versions 


Fully supported; iCs easier, faster, and more productive than ResEdit 
Safer memory-based, not disk-file-based, design and operation 
All file information and common commands in one easy-to-use window 
Compares resource Hies, and even edits your data forks as well 
Visible, accumulating, editable scrap 

Searches and opens/marks/selects resources by text content 
Makes global resource ID or type changes easily and safely 
Builds resource files from simple Rez-like scripts 
Most editors DeRez directly to the clipboard 

All graphic editors support screen-copying or partial screen-copying 
Hot-linking Value Converter for editing 32 bits in a dozen formats 
Its own 32-bit List Mgr can open and edit very large data structures 
Templates can pre- and post-process any arbitrary data structure 
Includes nearly 200 templates for common system resources 
TMPLs for Installer, MacApp, QT, Balloons, AppleEvent, GX, etc. 

Full integrated support for editing color dialogs and menus 
Try out balloons, ictb's, lists and popups, even create C source code 
Integrated single-window Hex/Code Editor, with patching, searching 
Editors for cursors, versions, pictures, bundles, and lots more 
Relied on by thousands of Macintosh developers around the world 


To order by credit card, or to get the latest news, bug fixes, updates, and apprentices, visit our website.. 

www.mathemaesthetics.com 














MAKING YOUR 
APPLICATIONS 
SELF- 

INSTALLING 


By Kenneth H. Wieschhoff, Jr. 


Self-Installing Applications 


Or “How / became Installer Free'' 


Introduction 

Tlie last step in any software development p^roeess is to 
create an installer, This can be Apple's PackageMaker, 
InstallerVise by MindVusion, and the like. By making your 
application self-installing you can update your frameworks, 
libraries, (and even kernel extensions) dynamically prior to 
nmning your main application. Your users can run your 
appliciation anywhere and you can include incremental updates 
to your software. This makes a more enjoyable user experience. 


picce,s. In addition to making source control easier to manage, 
it will simplify creating tlie "move” scripts. More on diat later. 
Here's an example of a folder layout for MyApp: 

MyApp^lication 

JVIyApp (the main (real) application) 

MyFramework 

MySciflnstaller (also pnjduces an application called MyApp) 

You1l use Project Builder to create a new “Cocoa 
Application” in your (new) MySelflnstaller directory. Let's have 
a look at the main code: 


The SECRE'f 

In short..,. Bundles! To the user your application looks like 
a single item, but in reality it can be an entire suite of tools. You 
create an installer appliotion that checks your support flle.s 
(frameworks, kexts, lil^raries, et. al.) are present and up to date. 
Missing/outdated items are installed using Apple's Authorization 
Services API Finally, this Installer launches the main application 
and ejuits. You store all ihe items, including the main application, 
in tlie Resources Folder within tlie Installer application. 

I'he Steps 

Here’s a checklist of thing to do: 

Create the self-installer application. Add your main 
application's icon. 

Write code in main to verify your support items are installed 
and up to date, and then launch the main application. 

Create the .scripts which will install a given .siipptm item. 
Autliorization Services will run tliese scripts for you at a 
privileged level. 

Create “mfjve” sc:ripLs to assist the build proc:ess, which mtwe 
your support files and main application irom their respective 
build dtreaories into the Resources folder within the InsiaUer 


CltEAIE THE SELF-lNSTAI,i.KR APPUCATION 
When Fm developing a softvt^are produa that contains 
many different parts, I usually create a folder to hold all the 


LLsting main^m 


mln.m 

Check if suppon items exist and are up-to-date and then Uundi the main application, 


^import <Cocoa/Cocoa.h> 

elude <Seenrity/Atitho rizBt ion. h> 
/finclude <Security/AuthorizationTags.h> 
^ilnclude <s1:di0.h> 

^include <unistd.h> 
fciclude <syfi/param.li) 


bool CheckIteiiiUpToI}ate(char 'where, char *what) j 

QSStatus DoInstalKehar : 

void LaunchMainApplication(): 


AuthoriaationRef gAuthoriaationRcf ~ 0: 

int msin(int arge, const char *argv[]) 
f 

NSAutoreleas^Fool ‘pool-f[NSAutoreleasePooI aliocl InitJi 
OSStatus stat ^ noErr: 


If { 1CheckltemUpToDate(”/Library/Frameworke/", 
"MyFrajttework, framework'')) 
stat = Deinstall ("InfitallFranevork. sti"] : 


if { stat noErr) 

LatmchMainAppllcationO ; 

// Release the anihoraation relercnce 
if{gAuthorizatlouR^f) 

AuthorIzatlonFree(gAuthorizationRef. 

kAuthorizationFlagDefaults); 


[pool release]; 
return (EXIT^SUCCESS): 


Ken WieschhoIT lives nor Atlanta and works for Altea 'therapeutics by day as an 8051 embcddcxl programmer (and some Windows MFC/GUI stuff) 
and Eskape labs by night where he does Cocoa programming (and occasionaUy device drivers) for their MyTV product line. Weekends you can find 
him scuba diving, riding his new Honda Valkyrie Rune, pickin’ a guitar and eating grits. He can l^e reached at weesh^mindspringTom. 
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Xserve 


Density optimized rack mounted Mac OS X Server 



UNIX-based Server Solutions from Apple 

Nearly half a terabyte of storage per lU 
630 gigaflops of processing power 
Hot-Swappable drives 

Industry-standard lU rack-optimized design 


There has never been a better time to buy.. 

Small Dog Electronics carries 
factory refurbished models too 
offered at substantial savings! 

(subject to availability) 



§niall Dog 

Electronics 

www.smalldog.com 


1673 MAIN STREET. ROUTE 100, WArrSFIELD, VERMONT 


C5 Apple Specialist 

To learn more: http://www.smalldog.com/xserve/ 























































































Main checks that the framework is installed on the user's 
system and installs it if it’s out of date or missing. It then 
launches the main application and then quits, (Noiiceat>ly 
absent in this example is some way to alert the user that 
installation of an item failed.) 


Listing 2; main.m 

'fhe Check] itniUp'roDuie checks lo see if a i^ven support item is up to date. 

bool Checklt&mUpToDateCchar ‘where^ char ‘what)[ 

// Guilt>^ until proven innocent. 

bool installNotNeeded = false: 

// Create the path to the installed support item. 

NSStriti^ ‘fullPath = 

iNSString stringWithFormat:§"%s%s". where, what]: 

// Gel Uie id uf Ihc'SupporUicms" folder 
// within the Resources folder of our application 
CFURLRef url = 

CFBundleCopyResou rcetlRL (CFBund 1 eGc-tMa 1 nRimil 1 e {). 
CFSTRC'SypportTtctus'q . NtP.L. NUhL); 

// Cm the path m the suppon item within 
// our own Rcs<jurccs bvindlc 
NSStrlng "supportFath = 

[NSStrlng stringWithFormat. 

[((NSURL *)url) path]. what]; 

// Ciei tlie bundle of die insiaJled support item 

NSBimdle *instExT = [NSBundle biiridle¥3thPath;fuUpathl : 

// If the extensiou ocists. . 
if (instExt) ( 

//.. bad it's dictionary. 

NSDictionary 'instaliedDict = linstExt infoDictionaryl; 

// Tf the dictionary' exists,., 
if (installfidDict) I 
// Get the .short version string 
NSStrlng 'vetaion ^ [InetalledDict 

obj ec tForKey;CFBundleShort Ve reionSt ring" ] : 

If (version)I 

// Ut) the entire thing again for the support ttxd 
NSBundle ‘local “ 

fNSBuridle hunrileWithPath:toolpnth] ; 

if ( local) I 

NSDictiOnary 'loeDict = [local iafoJlict ionary I : 
if (locDict) I 

NSStriug ‘ locVera = [iocDict objeetForXey: 

^"CFBundleShQrtVereionString"]: 

// (Compare the two strings for a match. 

if ([locVers compare: version] ^NSOrderedSanio) 
installNotKcedcd = true: 

I 

I 

I 

1 

I 

return installNotNeeded: 

I 


ChccklicmUpToDalc {:(>mpGres the Shon Version Strings of 
the installed item against the item packaged in the [lundle. 
Updating the version string causes the item to be re-inscalled. 
Up u> date items are nf)t reinstalled. 


The magic 

The Mithorization Serv'ices API provides a way to execute a 
script that needs privileges. 


Ustiiig 3: maln.m 

main.m 

Dolnstall get^ authoraatbu from the user to execute a script at a privileged level and 
exeaites the script. 

DSStatus Dolnstall(char *scriptName) 

i 

char iflyToolFath[MAXFAl’lilEW] : 

char *myArguments{2] = I NULL* NULLI: 

FILE ‘myfxpe = NULL: 
char myReadBufferil28] ; 

AuthorisationFlags rnyFlags = kAuthorizationFlagDefaultfi: 
Authorizationltem myTtecasf] “ i 
// For this example we're using the standard 
// commamd interprcter 

(kAuthorizatiouRightExecute, 
fittleuf”/bin/ah")< "/bin/sh". 01); 

AuthorizationRights myEights = I 

aizeofCmyltems)/sizeof(Authorizationltem)* myltems h 
OSStatus myStatus: 

//Tell the developer what script is being nm 

printf ('^Runni ng install script scriptNamel : 

// Store Hyc aiiduirizaiiort in a glolial so we don’t keep 
// asking the user for it once iVs given, 
if C gAutborizationRef =0) f 
// Create the aiithtnization reference, 
myStatus ” AuthorizationCreatc 
( NULL. 

kAuthorizatlonEmp ty Environment * 
myFlags* 

EtgAuthorizatioiiRef) t 

if[myStatus 1= errAuthorizatlonSuccesE) goto bail; 

// Set flags to create our auihori/ation environmeni. 

// Request to l>e pre-auihorized to run any tool. 

inyFlagE = KAuthorizatlonFiagDefaultE | 

kAuthnrizationFlagInteractionAllowed | 
kAuthorlzatioiiFlagFreAuthorize | 
kAuthorlzationFlagExtendRights: 

//'Iliis puts the Authorization dialog t>n the screen 
// and adds ilie authorization rights to the 
// anthori/Jitkin reference. gAuiliorizatifinRef. 
myStatus "" AuthorjzatlonCopyElghts 
( gAuthorlzailonRef, 

6(RiyEighta* 

NULL* 
myFlags, 

NULL ): 

if (myStatus !“ errAuthorizationSucccEs) goto ball; 

1 

// If we have a valid authorization refcnt'nee.,. 
if ( gAuthorlzatloiiRef) I 

myFlags = kAuthocizatlonFlagDefaulta: 

// Get the path for the script to mn 
myStatus " GetScriptPathfmyToolPath* scriptName): 
if(nyStatus) goto bail: 

myArgumonts[0] = myToolPath: 

// Finally, execute our script. 

myStatus = AuthorizationExecutaWithPrivileges 
{ gAuthorizationRef. 

"/bin/ah"* 
myFlags * 
myArgumeTits, 

SinyPi pe) ; 

if{tnyStalus = errAuthorizationSuccessJ f 
for C::) f 

// Scripts send output back Unougli myPipe which is 
// redisplayed on standard out 
Int bytesRoad “ read 

(fileno[myPipe), 
ntyRGadBuffer K 
slzeof{myReadBuf fer) ) 

// No more data! 

lf(bytGsRead < 1} 
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break: 

write(fileno(stdout)t rayReadBuffer* bytesRead): 

I 

i 

else 

prf31 tf("AuthorizationExeeuteWithFriyileges " 

“returned myStatits): 

bail; 

return myStatus: 


Doltistall creates an Authoiizarion reference if it clnctsn’t 
already exist, and uses that aulhorixatum reference to allow the 
user to add privileges to execute the shell script passed to it. In 
addition, any output prcxiuced liy the script will lie echoed on 
standard ouL 'rtris can lie a valualile del nigging aid wlien a 
script is giving you trouble as you can use standard shell 
commands like ‘"echo" and “pw'd^ in your script and .see the 
output in your Run wnndow in Project Builder, 

Lutnch the application 

'I’his is accomplished by calling fNSWorkspaee 
[auricliA[)plication]. 


Listing 4 : main.m 

mainm 

UujichMjiiiiAppliuaiion girls ^ pjiili in Uic: uiiibi iippliu^iitua ItJCiilLd wiUun the buiidle 
and liiunehtti it. 

void LaunchMainApplicationt) I 

// <ni the a'f to ihc ;ipp In Uie resuutecs folder 
CFURLRef url = CFBundleCopyResoureeURL( 

CFBund]eGetMainBund1 g()* 

CFSTR["HyApp.app"}, 

WULL. NULL); 

NSString 'path = [NSString striugWithl'ortiiatt 
@”%@Cont€nTs/MacOS/MyApp"> 

[{(MSURL ‘)url) path]J; 

[ [NSWnrkfipace aharadWorkspace] launchApplication:psth] : 


An installer script 

Once the user has gratited the applicaiion {XTUiission to 
perform privileged coninnindSj you can do anyiliing you need to 
iastall your supptiil item in the script. 


“^Warning***, Your script now has omniscient powers! You 
can cause irreparable damage to the user’s system in your script 
if you’re not careful. 
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listing 5: lnstallFramework*sh 

InstalllTamework.sl] 

Here's an example stripi whieh copies a framework to the system and calls 
iipdate_prt;bindmg to calculate the locations of functions witJiin a library so 
applications will launch faster. 

If I /bin/sh 

# chock if tho global franoworkn directory exists, 

II create it if not 

if I t -d /Library/Frameworks ]: then 
create 

mkdir /Library/Framaworks 

# set group to the administrative group 
chgrp staff /Llbrary/FraiaeworkE 

# allow group users to modify 
cbmod 775 /Library/Frameworks 

fi 

# make sure the framework exists within our application 
if L -d \ 

MyApp.app/Contents/Resources/SupportItems/\ 

MyFramework.framework ]: then 

# check if the framework exists In /Library/Frameworks 

# delete it if it is 

if [ -d /Llbrary/FramGworks/MyFramework.framework ]: then 
rra rf /Library/Frameworks/HyFramework.framework 
fi 

lif copy our framework to the system 
cp -Rp \ 

MyApp.app/Contents/Resources/Supportltems/\ 

Myframework*framework \ 

/Library/Frameworks 

it change file modes on the new framework 
chmod -R ogu+r \ 

/Library/Fr amewo r ks/MyF r ame work.fr amewo rk 

# call update^preblng 
/usr/bln/update_prebindlng files \ 

/Library/Frameworks/MyFramework.framework 

else 

it Perhaps you forgot to add the file to the framework? 
echo MyFramework.framework is missing from build! 
fi 


Last Step - “Move” Scripts 
When you’re building ihc fnsuiller, Prnjeci Builder makes it 
easy for you to [nove your supjiort iieiris and main applicalion 
into die Resources folder by adding an extra step to the build 
pr<K‘css. Select the Targets tab on the main project window and 
select the <MySelfInstaller> target. From the Project Menu, select 
**New Build Phase” and the ”New Shell Script Build Phase" 
submenu item. 

In the “Shell:" text area enter "/hin/sir if tliis is the shell you 
normally work widr (Note you can use any shell you’d like). 
In the .second text area enter "exec ./moveMyFramework.sh", 
Let’s look at an example of the script: 

Listing 6: moveMyFfafiiework.sh 

MovcMyFramcworft.sh 

This script copks the fnimework from a sibling directory tiiio our Supportltems 
foJdcc 

/jf! /bln/fih 

II if the framework already exists, delete It 
if [ -d •build/MyApp.app/Contents/Resources/\ 
SupportItems/MyFramework.framework" j : then 
rro -rf \ 

''build/MyApp.app/Contents/Resourcea/\ 

Supp 01 111 em s/MyF r amewo rk.fr amewo rk" 
fi 


ff Check the Supportltems" folder actually exists 
If [ ! -d \ 

"build/MyApp.app/Contents/Resources/Supportltems" ]; then 
mkdir \ 

"build/MyApp.app/Contents/Resources/Supportltems" 

fi 

# Finally, copy the framework 

cp -Rp ../MyFramework/build/MyFramework.framework \ 
build/MyApp,app/Contents/Resources/SupportItems 

DonT get confused by the multiple references to 
“MyApp", Remember, the goal is to make the user unaware 
theyTe actually running miilriple applications. You’ll want to 
udd your iipplicutioois icoas io the selbiastaller to complete 
the effect. 

Conclusion 

This approach has numerous advantages to rolling out new 
versions of your application and provides a very nice user 
experience, as the user only has to authorize once during the 
initial run of the application. Absent is a way to un-install the 
application and supporting files, lliis is left as an exercise for 
the reader. 

References; 

Authorization Sennees Reference: 

http://developer.3pple,com/documentation/Security/Reference/author 

izatjon_ref/ 
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Got a Great Idea? 

Don't just think about it, do it! 
We've got just the books to 
help you get hands-on with the 
hottest software on the market. 

The Painter 8 Wow! Book 
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Photoshop Restoration & 
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By Sherri Sheridan 
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By Eda Warren 
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Visual QuIckPro Guide 
By Joshua Marker 

0-321-11549-X • $24.99 • 392 pages 
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Norvell, & Brian Wotring 
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MOVIE REVIEW 


By Andrew S. Downs 

Revolution OS 


The rise of the free software and open 
source movements 


Introduction 

Every so often a movie comes along that tells a techie tale in 
jusl the righl way. Making the rounds righi now at film festivals 
and on various movie channels is an indejxmdeni film called 
Revolution OS. Produced and directed hy J T.S. Moore, 
Revolution OS tells the story of llsc rise- of the Frt^e Sofiware and 
Open Source movements. Using a com Innation of news biles, 
oimera shots of Silicon Valley, and occasional statisrics illustmiing 
the increasing adoption of liniix and f'iopiilarity of Linux-related 
Initial Public Offerings, the movie intersperses such leasers witli 
interviews with key players in these movenienis. 

The movie opens with Eric Ihiymond recounting an episode 
in wliicli he encountered tlic Micrt)sofL W of Consumer PrExlucts 
at a conference. Eric concludes the enetjunter hy telling the VP 
'I'm youVe worst nightmare.’' This ofiening excliange sets the 
lone for llie movie; a growing movement that threatens the 
dominance of Microsoft. 

1'he talking head format used for these interviews works 
IxrtlCT than you i night ex pea. The main playei-s are introduced 
witli little fanfare. This allows you to Ickus on the tnessage tlial 
each relays. We meet several of the players in the opening 
minutes; Erie Raymond, Linus Torv'aids, Hiuce Perens, and 
Richard Stallman. The interviews show the passkm as well as the 
facts. Tlie small amonm of naiTation and voiceover provicles 
some variety in the presentation, and in no way detracts from the 
message. There is nc^ evidence of "Hollywocxl" in this film. 

The lech talk is light. 'I'he most complex topic discussed is 
the distinction helween the monolithic kernel architecture of 
Linux and the microkernel-based GNU HURD, if you read Ciiff 
Stoll's f'he CuckcK)'s Egg, the superficial treatment of potentially 
complex topics \s similar though engaging. This makes the 
movie accessible to a broader audience. 

Eor example, Bruce Perens, the author of the Open Source 
Definition, discusses open source as a way for developers to 
collaborate on projects without restrictive tnielleciual property 
laws and contracts getting in the way. Those developers 
sacrifice Intel leaual property rights in an effort to increase the 


nuin()er of users of the sttflware. This could easily have gotten 
lx>gged down in legal terminology, hut Bruce makes die topic 
easily accessible. 

We also find out ihai the connections between the 
philosopher Stallman, the engineer Torvalds, and the companies 
that aim to bring these products to market are bavsed not on a 
bandwagon mentality but on real experience with the 
underlying products. Michael Tiemann of Cygnus Software and 
Dirty Augustin of VA Linux Systems, who serve as the film's 
primary enirepreneiirs, were both programmer.s who 
contributed to the GNU sofiware code base earlier in their 
careers. No doubt this enhanced their ability to make otherw'ise 
free tools a commercial .succe,ss. 

Anotlier indication of the .symliiosis betw'een companies and 
philo,sophers is Netscape’s decision to release its browser source 
code (the Moxilla project) as open .source based on the principles 
espoused in Eric RaymoncLs The Cathedral and the Bazaar . 
Fearing a Microsoft monopoly and jieiversion of HTML and 
H'ri'R, Netscape liecame the first commercial vendor to offer its 
source ctxie as a prfxlua. 

FREE VS. Open Soitrce 

The movie goes ro great lengths to balance the discus.sion 
between the Free Software Movement and Open Source. 
Although Linux and Open Source receive the lion's share of 
media attention, we find out that Richard Stallman and the Free 
Sofiware Foundaiion predate Open Sour’c by ten years or so, 

Free software and open source are not synonymous. Free 
software is more of a political stance than an economic one: 
"free" refers not to [irice hut to philosofiby. Free software ran lie 
used and moclifieti without restriction. In the proprietary, single 
vendor or non-free software world we know tliLs concept as 
[liracy, excejil w^herc very Iilx.Tal licenses apply. Free software 
began as Richard Stallman's personal crusade about twenty years 
ago. Inteiviews with Ifichard in the movie clearly bring out the 
zeal and passion in the man. What started as a configurable text 
editor (Emacs) in the 1980s evolved along several non- 
contiguous paths, including the Free Software Foundation's 
GNU project and ihe Open Source movement where T.inux and 
Apache remain the most obviou.s examples of succe.ssfLil 
projects into an essential element of our technology 
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infrastructure. Some businesses base their products on code 
originating from free software. 

Freedom to modify is a pillar (?f tliis philosopliy. The 
responsibility accompanying that freedom comes in the form of 
the GNU Public Licen.se (GPL). The GPL states that distributing 
a product tliat uses free software within its core or periphery 
(derivatives of the GPL differ) requires the distributor or vendor 
to also distribute or make available the product source code so 
that others may eojtjy the .same freedom to use and m<)dify\ 

Making money 

One imporlanl tgieslion with regard to both free software 
and open source software (wiiich l>y definition is frcc-ol-charge) 
is ‘‘How^ do you niake tnoney?'* At fii:st blush it tiiay appear 
inipossible. After all, I or any programmer or hacker with a 
comi^iler can download, modily, and build the iinished product. 
'I'hen I can simply give it to my friends and coworkers, right? 

Ye*s, you am if the license permits it. but your next question 
might ''How do 1 configure it for my sysiem?” Or “Wliy did it 
nor install properly on my system?" it you liave time and desire 
you may be able to determine tlie answers on your ow'n. Bur 
lousinesses typically do not plan for, p'^iy for, or sonic times allow 
tills experimentation to occur cm theii dime. They pjcfer to call 
or email someone else for support. 

And there lies the answer to tlic moneymaking question. 
'I'he rise in outsourcing encourages fimis that s[x^cialize in 
support (including packaging, installation, configuration, and 
usage issues) of open source and free software produc't.s. 
Businesses can then expense support costs by ])urehasing a 
pac kaged GNlI/IJnux product from a vendor such as Redllat, 
Caldera, SuSE, or VA Linux and receive ongoing support from 
outside the company. Tliis reduces or eliminates tile need for in- 
house expertise, thougli pockets of knowledge within the 
company will remain and likely grow. 

Microsoft 

Microsoft's rule in the nirjvic is cannon fodder ft}r several 
anecdotal episodes discussing encounters l>etween free software 
and open .source luminaries and Microsoft m:inagers and the 
com[xiny-at-large. One of tlic most memorable is Bill Gate.s' 
1976 letter to the Homebrew Computer Club, in which lie 
vetiially dubs those developers who used Microsoft's BASIC 
compiler without paying for it. In contrast, the Windows Refund 
Day protest in 1999 provided less drama, since Microsolt 
provided drinks rather than w^ater cannoas when the protestors 
showed up at their building. But the movie is not a Microsoft 
iiashlesl. Rather, it illastrates the reasons behind the rise of open 
source and free software, iliese people changed the world in 
response to the proprietar}^ softw^are philosophy, of which 
Microsoft is the most visible pro]K>nent. 

Apple 

So where is the Apple and Mac OS connection in all this? 
i'he movie di,sc'usses free softw^are (the GNU tools) and open 


source (Berkeley Unix) products that are familiar territory to Mac 
OS develo[:)ers with the rise of OS X. Hie GNU development 
tf)ois lie at the center of Projea Builder, the development 
environment that sliips with OS X. Berkeley Unix, itself an 
attempt to bring freedom to the category of ojxrating systems by 
competing with ATSiTs proprietary Unix, has over the years 
given rise to offshoots that use open source and collaboration as 
their development philosophy. FreeBSD is one of Uiose 
offshoots and sits near the core of OS X. (I’he Mach microkernel 
resides undemeath. Madi is anotlter open sourc*e projeci that 
receives little air time in the movie but broke new ground in 
kernel development.) 

At tlie other end of the Mac OS spectrum are technologies 
such as Aqua and QuickTime dial are unlikely to lx:come open 
source candidates since they are key to dilferentiatmg Mac OS 
from competing operating systems. 

Ill the middle lie exiension,s to the kemel and BSD 
subsystems, including Directciry Services and Rendezvous. Tiiese 
remain open source projects maintained by Apple and interested 
developers outside the com[:>any. 

SuGGF.STEn Reading 

I enjoyed this movie, but it may leave nsome tedmophile.s 
longing for more. It.s treatment of technical issues is light. If you 
find the movie intriguing or simply want to learn more alx)ut the 
[People, idetis, and products involved, here are several lxx)ks 
you should consider reading: 

Tlie Cathedral and the Ikzaar: Musings on Linux and Open 

S ource Iw an Acddental Revolutionary , by Eric S. Raymond, 
1999, 2001. O'Reilly and Associates, Inc. The essay.5 in this 
Ixxjk caiiture the Cnssence of tlie tipcn source philosophy and 
attempt to quantify and explain the "why" behind the "whatL 
Free as in Freedom: Richard Stallman's Crusade for Free 

Software, by Sam Williams, 2002. O'Reilly and As,s(x:iaies, 
Inc. '['Ills hook presents Richard Stallman’s free softw^are 
philosophy and liistory through recaps of interviews witli the 
man himself and other sources. 

Totv^alds and David Diamond, 2001, HajperCollins. Hall- 
wriUcTi by Linus Torvaltis, witfi the lialance consisting of 
inteiview^ recaps, this book provides insiglit into Linus' 
character and view.s on life, Linux, and the pursuit of family. 
Open Sources: Voices fn)m the Open Source Revolution , edited 
by Chris DiBona, Sam Ockmati, and Mark Stone, 1999- O'Reilly 
and Associates, Inc. 'Fhis contains essays by Stallman, 
Raytnonci, Torvakis, Fenms, Tiemann and oihera. 

Rebel Code: Tlie Inside Storys of Linux and the Open Source 

Revolution , by Glyn Moody, 2001. Perseus Publisliing. An 
account of ihe rise t)f Linux from a spare-time college project 
to its dominance today. 

Also, clieck out the Revolution OS wah site at 

http://www.rGvolution-os.com/. 
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By Scott Knaster 


Book Review: Mac OS X Hacks 


When Apple decided lo fuse ihe Mac OS wilfi Unix and 
NeXT software, it created a unique stack of code that shows its 
varied parentage; Mac OS when youTe in Aqua, Unix when 
youTe typing at tlie command line in Terminal, and NeXT when 
you use Cocoa. But it\s not just software that Apple has gathered 
together. Mac OS X has also brought new conmiunities of 
developers and users into the Mac universt^ Unix aficionadt^s 
and open source advocates wlio never gave Apple a second 
thought have Ix^en drawn into the new world of OS X. 

Mae OS X Hacks is one resLili of this new conimunity. It's |>an 
of a series from O^Reilly, a company long known for lxx)ks alxjut 
cutting edge and non‘proj:>rielary (and non-Apple) technologies, 
and now veiy' active in pul^lislitng Mac lxK>ks since the advent of 
OS X. Mac OS X Hacks feels like a lKx)k tliai's truly native to its 
subject: not a Unix lxx)k, nor a NeXf lxK>k, and clearly not a bcx>k 
from OS 9 days, but made h>r the new Mat universe?. 

Arrangement 

Mac OS X Hacks, siihtilled 100 Industrial-Strength Tips 
& T<h)Is. is oiganized initj nine chapters, using groupings LltaL 
probaf^ly work just as well as any other: chapter titles include 
l'ile.s, Startup, Multimedia and the iApps^ and Networking. 
Another useful organization might have been according Us type 
of user: regular folks, programmers, network admini.strators, and 
so on. For example, the Networking chapter includes tips on 
how to share files lietween Macs and Windows computers, 
inieresting to many users, and how to set u[> your own dt>niain 
name service, which is interesting but much more specialized. 

In addition to the chapter organization, the hacks are 
numlxrred consecutively from 1 to 100, and every page includes 
the cunent hack's number in a nice purple inset in the corner. 

Tips for the Resi or Us (and Ouk Moms) 

One of the best features of Mac OS X Hacks is that many 
of the tips are potentially useful for just about anybody running 
OS X. Tfiere's a tip on backing tg), another r>n getting rid of files 
in the trash that don't want to leave or CDs that won't eject, and 
one on how to share your internet connection. Airhough ifs 
likely that mt>st people buying a kK)k with "Hacks" in the title 
are ready for advanced topics, these everyday tips are generally 
useful and can l>e passed on to the less technically savvy folks 
who depend on you for supfjort. 

Some chapters, in particular the one entitled The User 
Interface, describe how you can gain greater control of your Mac 


using shareware and commercial utilities. For example, you’ll 
find descriptions of a couple of alternatives to the Dex'k, and 
various tips on how to re.store lost features from OS 9- 

DEVEI.OPE11S On!.y (Unix havored) 

Mac OS X Hacks has a fine collection of tips that are 
(jracticah buX primarily useful to developers or other advanced 
geeks. A useful section sheds light on whar's in an application 
package and how you can mess around witli it. There are also 
sections on secure tunneling, remote login with SSll and 
messing around with WebDAV and FfP servers. 

The book does a good pb of avoiding becoming a complete 
Unix-fesi, but there are a lot of useful Unix-based liacks, 
including an entire chapter called Lfnix and the Terminal, Tlie tip 
called Top ICS Mac OS X Tips for Unix Geeks is self-explanatory 
and useful for the incoming Unix crowd. Other sections in the 
Unix chapter provide information on how to get the most out of 
'lerminaf how to use sudo, and how to open files and 
applicatit>ns iLsing the cornmaitd line. Tiiis chapter is particularly 
useful to old Mae folks just getting a handle on Unix. 

It's Educational 

Some of the hacks presented in Mac OS X ilacks are not 
pmciic'al tips per se, but m.stead provide overview Information on 
htjw particular features work. Although tliese tips miglit not l>e 
immediately Liseful, they’re quite handy for inaeasing your geneml 
OS X knowledge, llie very first hack, Understanding and Hacking 
Ycjtir User Ace<3unt, gives a gcxxl over\^iew of this useful topic 
whid 1 is ratlier alien to OS 9 lolks. Another section updates file tyj^e 
and creator codes witli OS X information. A couple of sections 
prcjvide nifty insight into what goes on when O.S X starts up. 

Is This Tip Reauy Necessary? 

With too hacks, not every one will he useful, educational, or 
fun, Il’.s a .safe l)et that not a lot of readers will really be interested 
in installing the Postgre^QL database or Setting a Password in 
Open Firmware. Still, even these topics can satisfy your 
intellectual curiousity. 

Conclusion 

The test of mexst "tips 8s. tricks" lxx)ks is in tlieir practicality. Tlie 
contents should be fun and interesting, but if‘ they’re usetiil too, die 
book is a success. Mac OS X Hacks does an excel lent pb of 
delivering a solid package of topics diat are interesting and useful. 
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Track 


Keep track of every second of your time and bill 
for it with Time Track! Built in instructions make 
it easy to use- It is a simple way to manage your 
billable time for multiple projects and create o 
web page to show to your clients. Only $24.95 
per single user license per platform. Finally! A 
versatile time tracking solution for Macintosh, 
Windows, and Palm I 



www.trinftnitysoftware.com 



The Dock with more than one dimension* 

Create multiple docks of any size, assign hot keys and 
even put the Trash back on the Desktop. A flexible and 
feature-laden tool for power^users. Runs natively on Mac 
OS X and 9 in five languages. 

” * * you made ihe switch to OS X a lot easier for me../- 8oh LeTtIus 

^.DragJhmg am rightfully k cotted ua mdispembk aifi to working with your 

rnc.r-MocOserm 

Download a copy now from www.dragthmg.com. 


/ 


Trapcode * plug-ins lor Adobe® After Effects® 

Trapcode Shine is o fast light effect plug-in. The effect looks 
very much like volumetric light, but is actually a 2D effect. 
There are special controls to make shimmering lights and 
numerous coloring modes. This is an effect that you see 
everyday on TV and in many movie titles. Shine is available 
for Mac, Mac OSX and Windows. 


WWW. trapcode, com 


Eudora Internet Mail Server (EIMS) 
3.2 is the latest version of the most 
popular Internet moil server for the 
Macintosh. If you need to handle 
email for a dozen users, or 
thousands of users, EIMS is □ 
reliable and easy to use solution. 

EIMS 3.2 is available far IJSS40Q.OO, there ore nc limits on the number of users 
that can be added, and free email support is included. 

For more irtformatior^, see 

http;//www.eudorQ.co.ni:/ 


GraphicConverfer converts 
pictures to different 
formats. Also it contains 
many useful features for 
picture manipulation. 

See wwwJemkesoft,com 

for more information. 
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Multiple formats. Multiple platforms. 
Complex installers. 

Maddin solves Ihe oompresskm and installation puzzle. 


Trying to figure out how to handle multiple 
compression formats and platforms? 

The Stufflt Engine solves the compression puzzle. 

Aladdin’s StulTlt Hngine SDK: 

> Adds value to your application by integrating powerhil compression and encryption. 

> Is the only tool that supports the Stufflt file format. 

>■ Provides a single API that supports over 20 compression and 

encoding formats common on Macintosh, Windows, and Unix. 

>■ Makes self-extracting archives for eitlier Macintosh or Windows. 

> Available for Macintosh, Windows, Linux, or Solaris. 

Stufflt Engine SDK 

The power of stufflt in your software. 


Licences sturt as low 
as $ Wycar 

To loani more, visit: 
www.stufflt .com/sdk/ 




Looking for the easiest and fastest 
way to build an installer? 

Stufflt InstaUerMaker completes your puzzle. 


It's not enough just to write solid code anymore. You still have to write an installer 

for your users. Stufflt InstaUerMaker makes it simple and effective. 

> Stufflt InstaUerMaker gives you all the tools you need to install, uninstall, 
resource-compress or update your software in one complete, 
easy-to-use package. 

> Add marketing mu.scle to your installers by cu.stomizing 
your electronic registration form to include surveys 
and special offers. 

>► Make demoware in minutes. Create Macintosh 
OS X and Macintosh Classic compatible installers 
with Stuffll InstaUerMaker. 

Stufflt InstaUerMaker 

The complete installation solutlonr 


Prices start ai $250 

To leant more, visit; 
www.stufliuajai/ 
installcrmakcf/ 


^^^Aladdin 

w\Systafis 

www.stufnt.com 
(831) 761-6200 

O 2002 AJoddift Syjiemi, 

Inc Shifllt, Stuffll 
InsidllcrMakef. emd Siufftr 
tngine SDK ore trodemorks 
gt Abddin Syainnt, Inc. The 
Abctdin logo a o rogislijfBd 
trademork. All niher procJucIi 
ore trDfWiarki or regijtered 
lrad«moiis of iheir fespaclive 
holcbn All Righbt Rcsftrved 
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Thanks 

g,«at vacation. 

Missing you 




^.23.0.192 

c/0 My 

24-7 Relief F^njpr^aO'C.^^I' 

tC"” 


Revolution 2,0; the English like language designed around the way you think. § 
Develop and deliver on Mac OS X, Windows and Linux ^ 

(not to mention 10 other platforms). -Is * ;; 

s^>wv 7ake the EngJish language, add elegant XML, more SQL databases than you care to learn, 

intrinsic video capture/Unicode^CGI scripting, sophisticated Reports,and build your solution faster than anyone e\s^!^ 
Jaguar, Panther, XP? Revoiution lets you eat platforms for breakfast. And speaking of eating, our Cookbook of examples 
gets you up/running, and productive NOW. You can join the Revolution for as little as $99... ^ 

. Build with It deliver with it love It - and still have time for vacations. 

limited time, your MacTech special lets you get 100% of the Revolution for 15% off - 
" . go to speciaLrunrev.com NOW. Thousands of developers have already Joined. 

. Don't letthe Revolution in modern coding start without you... 


Software At The Speed Of Thought 












